Agathon

Bring your own keys. No AI credentials ship with this source; whoever runs an instance supplies their own keys (see SETUP.md).

License: FSL-1.1-ALv2. Read, modify and self-host freely; do not offer it as a competing service. Each version becomes Apache-2.0 two years after release. See LICENSE, NOTICE, CONTRIBUTING.md and THIRD-PARTY-NOTICES.md. The tldraw SDK is licensed separately and needs its own key in production.

An AI whiteboard that tutors students in real time. Students draw on a tldraw canvas; after a short idle pause the app captures the viewport, sends it to a vision model and draws feedback, hints or a worked solution back onto the canvas. Handwritten math is recognised with Mathpix, and an optional voice tutor (OpenAI Realtime) can look at the workspace and talk the student through it.

Architecture

browser (Next.js App Router, React 19, tldraw 4)
  |  Supabase JS: email/password auth, whiteboards/user_settings/bug_reports via RLS
  |  authedFetch(): POST /api/* with Authorization: Bearer <supabase access token>
  v
Next.js route handlers (src/app/api/**, Node runtime on Vercel)
  |  verify JWT -> rate limit -> validate body (zod) -> call provider
  +-> OpenRouter   text + vision models (Live checks, hints, worked steps, workspace analysis, credits); never image generation
  +-> Mathpix      handwritten math -> LaTeX (optional)
  +-> OpenAI       Realtime voice token (optional)
  v
Supabase: Postgres (RLS) + Auth + Storage (board-assets, training-data)

Key directories:

Path	What
src/app/page.tsx	Dashboard: list / create / rename / delete boards
src/app/board/[id]/page.tsx	The canvas, AI loop, autosave, voice tutor
src/app/train/page.tsx	Trainer-only page that records before/after samples
src/app/api/**	Route handlers (all require a Supabase JWT)
src/lib/api-client.ts	authedFetch / apiJson / ApiError used by the client
src/lib/server/**	Auth, env, rate limiting and provider helpers for routes
supabase/migrations	Database schema (see below)
docs/ARCHITECTURE.md	Request flows, security model, known limitations

Data model

Defined in supabase/migrations/20260911000000_init.sql. Every table has RLS enabled, anon has no grants, and authenticated users can only see rows where user_id = auth.uid().

Table	Purpose
whiteboards	One row per board: title, data (tldraw snapshot jsonb), preview thumbnail, version, deleted_at (soft delete). Owner CRUD.
whiteboard_snapshots	Board history for an operator's restore: the state a save replaced, at most every 10 minutes and before a wipe; newest 8 + one a day for 7 days, within 4 MB per board (20261003000000_snapshot_retention.sql). Written by trigger only; owner read.
board_assets	Registry of objects in the board-assets bucket, for garbage collection. Owner CRUD.
user_settings	features jsonb (feature-lab toggles). Owner read/insert/update.
bug_reports	Insert-only from the app (message, screenshot, diagnostics, client log ring buffer). Read via the dashboard/service role.
trainers	Allow-list of user ids who may use /train. is_trainer() is used by RLS. Self read only.
training_samples	Before/after samples recorded by trainers (append-only).

Storage buckets:

• board-assets (public read, 15 MB, images): owner writes only under <uid>/<boardId>/.... Target home for canvas images so whiteboards.data stops carrying base64.
• training-data (private, 10 MB, PNG): trainers write/read only under <uid>/<sampleId>/....

Local development

npm install
npx supabase start          # needs Docker; prints API URL + anon key
npm run db:reset            # applies supabase/migrations from scratch
cp .env.example .env.local  # fill in the keys below
npm run dev                 # http://localhost:3000 (pretty pino logs)

Other scripts: npm run typecheck, npm run lint, npm test (vitest), npm run build, npm run db:push.

Environment variables (.env.local)

Mirrors .env.example (which carries per-variable comments, sources and local defaults; src/__tests__/envExample.test.ts keeps the two in step with the code). Cloud/Vercel placement: docs/RUNBOOK-supabase.md section 5.

Name	Required?	Used for
NEXT_PUBLIC_SUPABASE_URL	yes	Supabase project URL (browser client + server JWT verification + scripts)
NEXT_PUBLIC_SUPABASE_ANON_KEY	yes	Supabase anon/publishable key (same users)
OPENROUTER_API_KEY	yes	All image/vision/Live model calls and the credits banner
OPENAI_API_KEY	no	Voice tutor (Realtime API). Missing -> /api/voice/token returns 503
MATHPIX_APP_ID	no	Handwritten math -> LaTeX (with MATHPIX_APP_KEY). Missing -> vision-only fallback
MATHPIX_APP_KEY	no	See above; both must be set
SUPABASE_SERVICE_ROLE_KEY	no	Server-only; declared in src/lib/env.ts but read by no route or script today
NEXT_PUBLIC_TLDRAW_LICENSE_KEY	no	Removes the tldraw watermark (host-bound)
NEXT_PUBLIC_SITE_URL	no	Sent as HTTP-Referer to OpenRouter; default http://localhost:3000
LOG_LEVEL	no	Server pino level, default info
NEXT_PUBLIC_LOG_LEVEL	no	Browser pino level (console + bug-report log buffer), default info
NEXT_PUBLIC_LIVE_MATH	no	0 hides the Live Math pipeline/UI; default on
LIVE_MODEL_CHECK	no	OpenRouter id override for Live check; default in src/lib/live/contracts.ts
LIVE_MODEL_SOLVE	no	Same for Live solve
LIVE_MODEL_VISION	no	Same for Live vision fallback
BASE_URL	no (scripts)	scripts/live-smoke.mjs: dev server origin, default http://localhost:3113

MISTRAL_API_KEY is no longer used (the /api/ocr route it once powered has been removed with the image pipeline). Delete it from any environment.

Creating a new Supabase project

The previous project was deleted, so production needs a fresh one:

1. Create a project at https://supabase.com/dashboard (any region; note the project ref from the URL and the database password).
2. Link the repo to it:

   npx supabase login
   npx supabase link --project-ref <ref>
   

3. Apply the schema:

   npm run db:push
   

   This creates all tables, policies, triggers and both storage buckets. Re-running is safe.
4. Auth settings: Authentication -> URL Configuration -> set Site URL to the production origin and add http://localhost:3000 to redirect URLs. Email/password sign-in is the only provider used.
5. Put the new URL and anon key into Vercel for every environment:

   vercel env add NEXT_PUBLIC_SUPABASE_URL production
   vercel env add NEXT_PUBLIC_SUPABASE_URL preview
   vercel env add NEXT_PUBLIC_SUPABASE_URL development
   vercel env add NEXT_PUBLIC_SUPABASE_ANON_KEY production
   vercel env add NEXT_PUBLIC_SUPABASE_ANON_KEY preview
   vercel env add NEXT_PUBLIC_SUPABASE_ANON_KEY development
   

   Repeat for OPENROUTER_API_KEY, and for OPENAI_API_KEY / MATHPIX_* if you want voice and handwriting OCR. vercel env pull .env.local syncs the development values locally.

Trainer allow-list

/train is gated server-side by the public.trainers table (the page also hides itself for non-trainers). After the trainer has signed up once, run in the SQL editor:

insert into public.trainers (user_id)
select id from auth.users where lower(email) = lower('[email protected]')
on conflict do nothing;

Deploying

The app runs on Vercel (project whiteboardstaging). vercel.json is intentionally minimal; the Next.js preset handles everything.

vercel            # preview deployment
vercel --prod     # production

CI (.github/workflows/ci.yml) runs typecheck, lint, tests and a build on every push and PR to main with dummy env values, so no secrets are needed in GitHub.

Troubleshooting

Symptom	Cause / fix
Every /api/* call returns 401 unauthorized	The Supabase session expired or the token is for a different project. Sign out and back in; check NEXT_PUBLIC_SUPABASE_URL matches the project that issued the token.
402 credits_exhausted	The OpenRouter account is out of credit. Top up at https://openrouter.ai/credits; the dashboard banner shows the balance.
429 rate_limited	Per-user limit hit; the response carries Retry-After. Limits are per server instance.
503 voice_unavailable	OPENAI_API_KEY is missing or invalid in that environment. Voice is optional; everything else keeps working.
503 feature_unavailable	The route's optional provider (e.g. Mathpix) is not configured in this environment.
502 upstream_error	OpenRouter/Mathpix/OpenAI returned an error; check server logs (LOG_LEVEL=debug).
Board save fails with a timeout (Postgres 57014)	The snapshot is too large because images are still stored as base64 in whiteboards.data. Delete large pasted images, or ship the board-assets offload.
npx supabase start fails	Docker is not running, or ports 54321-54329 are taken (npx supabase stop --no-backup then retry).

All error responses from /api/* have the shape { "error": "<code>", "message": "<human text>" }.

Live Math (realtime math & STEM)

Live Math is an always-on layer on the board (toggle next to the Off / Feedback / Suggest / Solve tabs, persisted per device in localStorage under agathon.live.v1). It turns each handwritten line into a native, editable KaTeX math shape about a second after pen-up and runs an offline mathjs engine for instant checks; a streaming LLM is used only for the why and for hints, and only when the help mode allows it.

What a student sees after writing a line:

When	What
~0.6 s	Quiet gate ends; strokes are clustered into lines and sent to POST /api/live/recognize (Mathpix v3/strokes, ~300 ms; vision-model fallback when Mathpix keys are absent).
~1.2 s	A gray typeset "echo" appears right of the ink. The local engine adds a result chip (calculator rule), a green check or amber dot versus the previous line, a "Solved" chip on a correct final line, or a graph card for y = f(x).
~2–3 s	In Suggest/Solve, a mismatch triggers POST /api/live/check (SSE); the first hint card streams in below the echo. "Solve steps" streams worked steps from POST /api/live/solve.

Modes: Off = echoes and results only, never an LLM call. Feedback = location-only marks. Suggest = one Socratic hint per line. Solve = steps and full solutions on request. The legacy image-overlay pipeline is kept for non-math ink (diagrams) and via "Draw help" in the Live menu; its idle trigger is 4 s while Live is on.

What runs where:

• Browser: stroke clustering, payload normalization, KaTeX, the mathjs engine (evaluate, simplify, solve linear/quadratic/cubic, derivatives, numeric integrals, units and physical constants, step equivalence, chemistry balancing, graph sampling), placement and the silence policy (src/lib/live/**, src/shapes/**, src/components/live/**).
• Server: src/app/api/live/{recognize,check,solve}/route.ts behind the same auth, zod validation and per-user rate limits as every other route; prompts in src/lib/server/prompts/; streaming helpers in src/lib/server/sse.ts and openrouter.ts. Model ids default from LIVE_MODELS in src/lib/live/contracts.ts and can be overridden with LIVE_MODEL_CHECK, LIVE_MODEL_SOLVE, LIVE_MODEL_VISION.
• Persistence: math and graph shapes are ordinary tldraw records, so the existing snapshot autosave stores them. The shape utils are registered on both <Tldraw> mounts (board and train) so any saved board loads; NEXT_PUBLIC_LIVE_MATH=0 hides the pipeline and UI without unregistering the shapes.

Keyboard: m selects the Math tool to type a LaTeX shape; double-click an echo to fix a misread line (the engine re-checks it without calling Mathpix).

Testing: npm test (356 unit tests incl. engine, clustering, policy, placement, shapes round-trip, SSE parsing), node scripts/live-smoke.mjs against a dev server + local Supabase (auth, recognition, streaming, rate limits), and the manual checklist in docs/LIVE-MATH-SPEC.md §10.3. Voice tools for Live (read_live_math, place_math, plot_function) are implemented and unit-tested but not yet wired into the voice session.