Home

Deutsch· — project wiki

This is the knowledge section for deutsch-app: an offline-first German-learning PWA built on a language-agnostic engine with swappable content packs.

The README is the front door — what the app is, screenshots, and how to run it. Everything that needs more than a landing page lives here.

Pages

Page	What's there
Architecture Overview	The two-lane design, the tech stack, and a map of the repository
Offline-First Sync Model	Per-slice merge semantics, tombstones, and independent LWW clocks
Lesson Engine	Data-driven lessons, the exercise registry, and the queued progress lane
Security & Role Architecture	Key boundaries, RLS, the AI boundary, and the avatar pipeline
Operations Runbooks	OAuth, email templates, migrations, and the production apply drill
Local Development	Full setup, every npm script, and the troubleshooting that actually comes up
Contributing & Quality	Testing philosophy, conventions, and how work lands

What lives here, and what does not

This wiki is a separate git repository from the app. It is not covered by CI, the pre-commit hook, PR review, or branch protection. So the split is deliberate:

• Here: evergreen knowledge for humans — how a subsystem works, why a decision was made, how to operate the thing. Content whose correctness is not pinned to a particular commit.
• In the repo, reviewed in PRs: anything versioned with the code.
  • docs/api/ — API contracts, true only at the commit that ships them.
  • docs/superpowers/specs|plans/ — per-mission designs and implementation plans; historical records, not living documents.
  • AGENTS.md — the single source of truth for conventions and product decisions. When this wiki and AGENTS.md disagree, AGENTS.md wins and this wiki is wrong.

Settled product decisions

These come up repeatedly and are closed. The reasoning lives in AGENTS.md.

• German stays the only pack. The multi-pack engine work is kept — it is why the engine is clean — but shipping a second language is not the goal. The German flavour is the brand.
• Passwordless is the design. Email codes or links, Google, GitHub, and Apple (where enabled) all land in the same Supabase session flow. There is no password anywhere in the app; adding one would be a standalone epic with a security review, not a settings line item.
• card.freqRank is never surfaced. Leipzig is a news corpus, so frequency there is not usefulness — die Polizei outranks die Frage by an order of magnitude. That needs different data, not a better design.