MatheLern

Interactive math-learning web app for the Bavarian LehrplanPLUS curriculum, covering three school tracks: Realschule (grade 5), Mittelschule M-Zug (M10), and Fachoberschule (FOS 11). Each track has one fully-built pilot topic (lesson + adaptive exercises) and a seeded, unpublished topic list for the rest of that track's curriculum:

• Realschule: grade 5 "Das Stellenwertsystem"
• Mittelschule M10: "Potenzschreibweise & Potenzgesetze"
• FOS 11: "Lineare & quadratische Funktionen" (shared by every Ausbildungsrichtung)

Gymnasium was removed (see migrations 0009-0010) in favor of this lineup — its content, grade rows, and the gymnasium_g9 track are gone from the app, though the enum literal itself stays defined on school_track (Postgres has no DROP VALUE; nothing references it any more).

A grades table keyed by (grade_number, school_track) is what makes this possible — e.g. grade 10 would exist once per track that teaches it, as separate rows (see supabase/migrations/0005-0007, 0009-0010).

See the full architecture/plan behind this build for context on design decisions, data model, and the adaptive difficulty algorithm.

Also in this repo

jaegerpruefung/ is a separate, self-contained app for preparing for the German hunting licence exam. It has bilingual DE/EN lessons, an AI tutor chat, quizzes and a web-research collector agent. See jaegerpruefung/README.md.

Tech stack

Next.js 16 (App Router) + TypeScript, Tailwind v4 + shadcn/ui, Supabase (Postgres + Auth), Vitest for unit tests, Playwright for e2e (not yet written).

Setup

1. Install dependencies

   npm install
   

2. Create a Supabase project (EU/Frankfurt region, for GDPR data residency with minors' data) at supabase.com. This step needs a Supabase account — it can't be done from here.

3. Configure environment variables

   cp .env.local.example .env.local
   

   Fill in NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, and SUPABASE_SERVICE_ROLE_KEY from your Supabase project's Settings → API page. The service-role key is server-only (used by Server Actions and scripts/sync-content.ts to bypass RLS for account bootstrap, answer secrecy, and content sync) — never expose it to the browser.

4. Run the database migrations — in the Supabase dashboard's SQL editor, run each file under supabase/migrations/ in order (0001 → 0004), then run supabase/seed.sql. (If you have the Supabase CLI set up and linked to the project instead, supabase db push applies the migrations, and psql or the SQL editor can run seed.sql.)

5. Sync lesson content into the database

   npm run sync-content
   

   This validates every file under content/lessons/**/*.json against the zod schema and upserts it into the lessons table. Run npm run sync-content:check (no DB writes) to just validate — useful in CI/pre-commit.

6. Run the dev server

   npm run dev
   

   Open http://localhost:3000.

Verifying the pilot flow end-to-end

1. Register a student account (grade 5 or 6) at /register.
2. From the dashboard, open the one published topic for that grade and complete its lesson (Das Stellenwertsystem verstehen for grade 5, Bruchteile verstehen for grade 6).
3. Start the topic's exercises, answer a few — watch the difficulty tier and mastery score move, and the worked solution appear after each attempt. Answer wrong 3 times in a row to see the "struggling" nudge and remedial (easier) exercises kick in.
4. Visit /progress to see the topic mastery bar and any milestone badges earned.
5. Copy the invite code shown on the student dashboard. Register a parent account at /register/parent, enter the code on the parent dashboard to link the child, then open the child's detail page to see their progress and (after enough struggling) a generated recommendation.

Scripts

Command	What it does
npm run dev	Start the dev server
npm run build	Production build (also type-checks)
npm run sync-content	Validate + upsert content/lessons/** into Postgres
npm run sync-content:check	Validate only, no DB writes
npm run test	Run Vitest unit tests (lib/adaptive, lib/generators)
npm run test:e2e	Run Playwright e2e tests (none written yet)

This is the beginning of the README. Read the rest at the original. Read the full README ↗