synapze-how-it-works

Synapze Product & Architecture Walkthrough #

Key points #

  • Synapze transforms unstructured expert text into structured, usable learning lessons.
  • The process involves two passes with Google Gemini: first to normalize content into Markdown, then to generate a training kit (summary, concepts, flashcards, quizzes).
  • Data is persisted in Cloudflare D1 (SQLite at the edge), storing Markdown as the canonical long-form content and the training kit as JSON metadata.
  • Learners access content via the /learn route, with consistent navigation for summaries, flashcards, and quizzes.
  • The tech stack includes Astro 6 (with server output and Cloudflare adapter), React islands, Tailwind v4, marked for Markdown rendering, and mermaid for client-side diagrams.
  • No authentication is implemented in this hackathon build.

Context and explanations #

The core purpose of Synapze is to take "messy expert text" (e.g., transcripts, notes, .txt uploads) and convert it into structured, learnable content. Experts provide plain text input via the /expert UI.

When an expert initiates generation, the application sends a POST request to /api/generate. Server-side, Google Gemini is invoked in two distinct passes:

  1. Pass 1: Normalizes the source text into a structured Markdown document, which can include headings, lists, and optional Mermaid diagrams.
  2. Pass 2: Builds a "training kit" – a JSON bundle containing a summary, key concepts, steps, flashcards, and quiz items derived from the Markdown.

Data persistence uses Cloudflare D1. Each row in D1 represents a "kit," which is a single saved learning unit. A kit row stores the title, the generated Markdown body, a summary snippet, source type, timestamps, and a metadata column for the training kit's JSON. This approach deliberately avoids a single, large, and potentially fragile JSON document, making Markdown the canonical long-form content.

Learners access the generated content through the /learn route, which displays a library of available kits. Clicking a kit card opens /learn/[id]/summary, with dedicated sub-routes for flashcards and quizzes. Shared shell components ensure a consistent navigation experience across these learning modes.

The technical stack for Synapze includes Astro 6 configured for server output with the @astrojs/cloudflare adapter. React is used for interactive "islands" within the Astro framework. Styling is managed with Tailwind v4 via @tailwindcss/vite. Markdown rendering is handled by the marked library, and client-side diagrams are rendered using mermaid.

For this hackathon build, authentication is not implemented, relying on deployment boundaries for access control. The application supports a persisted light/dark mode toggle for a consistent study experience. Kits can be deleted from the library via /api/kits/[id], supporting both HTML form POSTs (with redirect) and JSON DELETE requests for API-style interactions.

To set up Synapze locally, the GEMINI_API_KEY (and optionally GEMINI_MODEL) must be configured in a .env file or as Wrangler secrets.

Diagrams # 

flowchart TD
    A[Expert Input: Plain Text] --> B[/expert UI/]
    B --> C{Generate Kit}
    C --> D[/api/generate POST/]
    D --> E[Google Gemini: Pass 1<br>Normalize to Markdown]
    E --> F[Google Gemini: Pass 2<br>Build Training Kit JSON]
    F --> G[Cloudflare D1: Store Kit<br>Markdown + JSON Metadata]
    G --> H[/learn Learner UI/]