Repository navigation
Architecture
See Vision for where this is headed. See ADR-Hosting-and-Backend for the hosting/backend platform decision behind the Next.js migration.
| Concern | Solution |
|---|---|
| Frontend | Next.js (App Router, TypeScript), client-rendered throughout |
| Auth | Supabase (Google OAuth) |
| Database | Supabase Postgres + Row Level Security |
| OCR | OpenAI Vision — photo sent directly to OpenAI, extracts text and describes visual elements in one pass |
| LLM | OpenAI API — BYOK, key held client-side |
| Styling | CSS Modules |
Upload textbook photos → a multi-agent pipeline extracts concepts and generates study questions (flashcards, choice, fill-the-gap, sorting) → study via flashcards, quiz, or scored test. Preps can be shared privately, via link, or publicly.
Every upload triggers a multi-stage pipeline. All LLM calls go directly from the browser to OpenAI using the user's key — there is no backend proxy.
- OCR + page structuring — each image goes to OpenAI Vision, returning text plus detected visual elements.
- Concept extraction — page text is processed in parallel and merged into a single, deduplicated concept list; the prep is also classified (grade/discipline).
- Question generation — question builders (one per question type) run concurrently, each followed by a review step; a rejected question gets a limited retry before its slot is left for the next run.
- Asset generation — questions that call for a visual are routed to a type-specific agent (formula, molecule, diagram); not every visual type is implemented yet.
photo(s) → OpenAI Vision → structured page (text + visual elements)
→ concept extraction (parallel, then merged)
→ classification + naming + question generation (concurrent, reviewed)
→ asset generation where needed
→ Supabase
Crash recovery: progress is checkpointed as the pipeline runs, so an interrupted attempt resumes without redoing completed work. This covers already-saved work — the pipeline itself only progresses while a browser tab is running it (see open questions below).
- preps — owner, generated pages, visibility, classification metadata.
- questions — typed content belonging to a prep, each with explanations and an optional visual hint.
- assets — a generated visual attached to a question.
- attempts — a scored study run against a prep.
Row Level Security scopes access to the owner; shared preps (link/public) extend read access to their questions and assets.
Browser → OpenAI API (user's key)
The key never touches any server. There is no backend proxy today.
Two environments, dev and prod, per ADR-Hosting-and-Backend. Every merge to the main branch deploys to dev automatically. A release process (semantic versioning derived from commit history, with a generated changelog) decides what's promotable; prod only ever deploys a released version, never an arbitrary merge, and that promotion requires manual approval. Rolling back prod means redeploying an earlier released version — no rebuild needed, since released versions are retained.
Cross-cutting decisions not yet made:
- Client-only vs. server-assisted execution. Generation only runs while the initiating tab is open. Fine today; blocks true walk-away resilience, video rendering, and possibly voice quality. Needs a decision on whether/how to introduce server-side execution without breaking the BYOK trust model.
- Per-user LLM transparency. Only a rolled-up token count exists today. A real per-call log depends on the answer to (1) for how tamper-resistant it needs to be.
- Content sourcing for images. Fetching internet content implies a server-side step or a curated/licensed source — undecided.