Build reports

# Auf Deutsch — Phase 1 Build Report

**Product:** Auf Deutsch — personalized German for English-speaking adults
**Developed by:** SFGOC Labs
**Phase:** 1 — Functional Prototype
**Status:** Complete. All Phase 1 flows are clickable end to end with no console errors.
**Persistence:** Local only (`localStorage`, key `aufdeutsch.learner.v1`). No backend is connected.

---

## 1. What Phase 1 delivers

A learner can, without any backend:

1. Land on the marketing page and understand the product.
2. Play a complete German lesson as a guest at `/try` (no account).
3. Create an account, sign in, request a password reset, or load the seeded Demo Learner.
4. Complete six-step onboarding and get a personalized dashboard.
5. Work through two fully functional Foundations units (Alphabet, Numbers) including graded drills.
6. Play both seed stories in four modes with the six *Versuch es!* activity types.
7. Review vocabulary, run a generated review session, and see every mistake filed by category.
8. Adjust learning, audio and accessibility settings, view plans, and reset all device data.

---

## 2. Feature-by-feature status

| # | Requirement | Status | Where |
|---|---|---|---|
| 1 | Landing page: hero, explanation, pathways, guest CTA | Done | `src/routes/index.tsx` |
| 2 | Guest lesson, no account | Done | `src/routes/try.tsx` (Im Café, all four modes) |
| 3 | Sign up / sign in prototype | Done | `src/routes/auth.tsx` |
| 4 | Forgot password / reset / email verification screens | Done (simulated, clearly labelled) | `src/routes/auth.tsx` |
| 5 | Demo Learner (Jeff, network engineer) | Done | `startDemo()` in `src/lib/learner-store.tsx` |
| 6 | Personalized onboarding | Done | `src/routes/onboarding.tsx` |
| 7 | Dashboard: streak, weekly target, due items, editable mix | Done | `src/routes/dashboard.tsx` |
| 8 | Foundations course shell, 10 units, 6 progress meters | Done | `src/routes/foundations.index.tsx` |
| 9 | Unit 1 Alphabet fully functional | Done | `foundations.$unitId.tsx` + `alphabetDrills` |
| 10 | Unit 6 Numbers fully functional | Done | `foundations.$unitId.tsx` + `numberDrills` |
| 11 | Reusable exercise engine, 6 exercise types | Done | `src/lib/exercises.ts`, `src/components/exercise/ExerciseRunner.tsx` |
| 12 | Vocabulary review + generated review session | Done | `src/routes/vocabulary.tsx`, `src/components/vocab/ReviewSession.tsx` |
| 13 | Mistake Memory (Meine Lernpunkte) | Done | `src/components/progress/MistakeMemory.tsx` on `/progress` |
| 14 | Subscription preview (no billing) | Done | `src/routes/subscription.tsx` |
| 15 | Learner settings incl. reduced motion, audio autoplay | Done | `src/routes/profile.tsx` |
| 16 | Persistent prototype state | Done | `src/lib/learner-store.tsx` |
| 17 | Build report | This document | `docs/PHASE-1-BUILD-REPORT.md` |

---

## 3. Exercise engine

`src/lib/exercises.ts` defines one discriminated `Exercise` union and all grading:

| Type | Interaction | Grading |
|---|---|---|
| `multipleChoice` | Tap one option | Index match |
| `arrange` | Tap tokens to build a sentence | Exact token order |
| `matching` | Pair German with English/number | Per-pair, all pairs required |
| `fillBlank` | Type the missing word | Case-insensitive, punctuation-tolerant, one-typo "near miss" (Levenshtein) |
| `substitution` | Swap one element in a pattern | Same text grader as `fillBlank` |
| `freeResponse` | Write a sentence | Required-keyword match plus model answer |

`ExerciseSet` renders any array of these, tracks a score, records every attempt, and writes
incorrect answers into Mistake Memory with the category, prompt, learner answer, correct answer and
explanation. Adding content never requires new UI code.

Verdicts are `correct`, `near` (understood but flawed) and `incorrect`. Near misses explain the fix
without punishing the learner.

## 4. Foundations units 1 and 6

- **Unit 1 — Das Alphabet:** all 30 letter cards with German letter names, approximate pronunciation,
  audio, "I know this" tracking; hear-and-select drill; letter-sequence drill; spelling practice;
  and 7 graded drills (J/W/V/Z contrast, letter-name matching, *buchstabieren*, *langsamer bitte*,
  email address vocabulary, dialogue building, free response).
- **Unit 6 — Zahlen und Zählen:** number tables with audio, the visual number builder (0–999 with the
  ones-first rule), and 9 graded drills (word matching, 42 word order, compound spelling, prices with
  a comma, `halb neun`, phone numbers, IT port 443, ticket counts, free response).

## 5. Mistake Memory

Every wrong answer is stored with `exercise`, `prompt`, `learnerAnswer`, `correctAnswer`, `category`,
date and status. `/progress` shows live records with category filters, open counts, "Mark reviewed"
and "Remove", above the static category overview. The store caps history at the most recent 100
records. Simulated pronunciation feedback is flagged `prototypeOnly` and labelled in the UI.

## 6. Settings and accessibility

- Lesson length, exercise type, daily goal, everyday/professional mix, goals, profession, interests.
- Pronunciation help (always / on tap / hidden) and phonetic style (simple / IPA / both).
- **Audio autoplay** — story scenes start themselves when enabled.
- **Reduce motion** — sets `data-reduced-motion` on `<html>`; global CSS neutralises transitions,
  animations and smooth scrolling.
- Articles are always written out, never colour-only. Skip link, labelled controls, `lang="de"` on
  German text, 44px minimum touch targets, mobile bottom navigation.

## 7. Prototype boundaries (deliberate)

- **Authentication is not real.** Any valid-looking email and a 6+ character password succeed. No
  email is sent for verification or password reset; both screens say so.
- **Demo Learner** is dev-only, marked with a persistent banner, and lives in one clearly commented
  block in `src/routes/auth.tsx`.
- **Speech** uses browser speech synthesis (`de-DE`), a stand-in for recorded native audio.
- **Pronunciation scoring is simulated and deterministic** (`src/lib/pronunciation.ts`) and always
  labelled as prototype feedback. No audio is analysed or uploaded.
- **No billing.** `/subscription` presents plans only; no Stripe, no checkout, no paid third party.
- **Progress data is per-device.** Clearing site data or "Sign out & clear device data" resets it.
- Levels A2–C1 and Foundations units other than 1 and 6 show structure and topics, marked as content
  in writing rather than finished lessons.

## 8. Persistence model (prototype data layer)

All browser storage lives in one repository module, `src/lib/storage.ts` — no component touches
`localStorage` directly. `src/lib/learner-store.tsx` is the single typed access layer above it.

- **Key:** `aufdeutsch.learner.v1` · **Envelope:** `{ v: 2, data: LearnerProfile }`
- **Versioned:** records written by an older build (unwrapped v1 payloads or `v < 2`) are read,
  merged with defaults and re-saved on load.
- **Corruption safe:** unparsable or foreign payloads are discarded, the device record is cleared and
  the store exposes `storageRecovered`, which renders an explicit recovery notice on `/profile`.
  No crash, no blank screen.
- **Synchronous writes:** the store mirrors state in a ref so a click that also navigates still
  persists (this is how `Continue as Demo Learner` survives the route change).
- **Reset:** `/profile` → *Reset prototype progress* behind a confirmation dialog; also `signOut()`
  for a non-destructive sign-out.
- **No sensitive data:** the record holds a first name, a placeholder email, learning preferences and
  progress counters. No passwords, tokens or audio are stored.

Stored entities: profile and onboarding answers, preferences (lesson length, daily goal, mix,
exercise mode, pronunciation help, reduced motion, audio autoplay), lesson and story completion,
exercise attempts, saved vocabulary with confidence and review labels, mistakes with category and
status, Foundations progress (letters, sounds, listening accuracy, speaking reps, numbers, units) and
the prototype streak / weekly minutes. Each maps 1:1 onto a Phase 2 Cloud table.

## 9. Verification performed

Playwright, 1280×1800 and 390×844:

- Landing → `Try a Lesson` → `/try` guest lesson renders and plays.
- `/auth` → `Continue as Demo Learner` → `/dashboard` with the demo banner visible.
- `/foundations/alphabet` and `/foundations/numbers` render every block including the drill sets.
- Vocabulary review session starts, grades an answer, and files an incorrect answer.
- `/progress` shows the live mistake record with review controls.
- `/vocabulary`, `/profile`, `/subscription`, `/lesson`, `/stories` all render.
- Zero console errors and zero page errors across the run. TypeScript check clean.

### Final Phase 1 pass (Playwright, 1280×1800 and 360×780)

- Full journey: landing → auth → Demo Learner → dashboard personalised to Jeff (`HALLO, JEFF`) →
  Foundations lesson → exercise graded → attempt, mistake ("Pronunciation") and letter progress
  written to storage → survives reload.
- All 16 routes plus an unknown URL render with content; the not-found route returns its own page.
- No horizontal overflow at 360, 390, 768, 1024 and 1440px; zero page errors, zero console errors
  (other than an expected 404 for the intentionally invalid test URL).
- Corrupted storage injected by hand: recovery notice shown, app fully usable.
- Mistake cards now offer inline *Practice again* with tolerant text grading; a correct retry marks
  the item reviewed.
- TypeScript check clean.

## 10. Recommended Phase 2 scope

1. Lovable Cloud: real accounts, email verification, password reset, cross-device sync.
2. Move `profiles`, `user_preferences`, `user_progress`, `user_vocabulary`, `user_mistakes` and
   `review_queue` behind the existing store interface — every read/write already funnels through
   `src/lib/learner-store.tsx`.
3. Recorded native audio replacing speech synthesis.
4. Real pronunciation assessment, replacing the simulated scorer behind the same interface.
5. A true spaced-repetition scheduler (dates instead of "Today / Tomorrow / In 3 days" labels).
6. Remaining Foundations units 2–5 and 7–10, then the full A1 unit set.
7. Stripe billing for the Lernender and Sprecher plans.