SKS Lotse
A web app to prepare for the theoretical exam of the German SKS (Sportküstenschifferschein) sailing license. The official exam catalog is free-text, not multiple choice — the learner writes an answer and has to judge for themselves whether it's close enough to the model answer. SKS Lotse tracks what a learner has actually retained, simulates the exam, and — on request — has an LLM compare the learner's free-text answer with the official one, suggest a grade and explain what was missing or wrong; the learner always confirms the grade.
What's different from existing apps (SKS-Buddy, the official SKS App — both already offer AI-graded free text): web-only (no app store), a learning status based on an estimated memory half-life rather than a streak, and the official Kartenaufgaben worked through task by task. Monetization is freemium without ads — pay per use for the AI check with a token balance — see docs/adr/0043 and docs/adr/0060 for the reasoning.
How it was built
Fully AI-built, human-directed, live in production. Code, tests, migrations, workflows and docs were written by Claude through Claude Code (apart from Dependabot's bumps). The human part: what the product is, which option to take, what counts as done and goes live, plus what only a person can settle — sailing domain, catalog and chart rights, prices, operations. Live on Render; first commit 2026-09-16.
What keeps the AI on course:
- Written rules: CLAUDE.md for working on the code; one owner document per topic, fixed in the same PR that makes it wrong.
- Recorded decisions: every non-obvious choice is an ADR, so a new session (or reader) learns why.
- Automatic gates: required CI checks with coverage and mutation-score ratchets, plus tests that guard the conventions themselves — see Testing & quality gates. Hooks and pre-commit catch the rest.
- A human merges: one branch per change, squash-merged via PR, auto-merge off.
Commits name the model that wrote them (Co-Authored-By):
git log --format='%(trailers:key=Co-Authored-By,valueonly)' | sort | uniq -c | sort -rn
Status
Live: email+OTP login, learning by topic with self-assessment against the official answers, Fokus and Auffrischen, the exam simulation (Fragebogen) with history and statistics, the Lotsen-Check (an LLM that suggests a grade, paid with tokens) with token packages bought through Stripe, and the admin tools. Also live: the Kartenaufgaben (all ten sheets), open to guests too, with their own Lotsen-Check. Not built yet: SSO, speech-to-text. What learners and operators can do today, incl. prices: docs/FEATURES.md; the technical current state and the full "not yet built" list: docs/ARCHITECTURE.md.
Tech stack
| Layer | Technology |
|---|
| Frontend | React (Vite) + TypeScript, Zustand, Tailwind CSS |
| Backend | Python 3.12 / FastAPI |
| Database | PostgreSQL 18 |
| Auth | Email + one-time code (OTP), JWT sessions (SSO not yet built) |
| Transactional email | Resend |
| Answer check (LLM) | Anthropic API (Claude Haiku 5.5 for catalog questions, Claude Sonnet for Kartenaufgaben), pay-per-use with tokens — ADR-0031, ADR-0066, ADR-0043, ADR-0058 |
| Payments | Stripe Hosted Checkout, fulfilled by webhook — ADR-0048 |
| Analytics | Umami Cloud (cookieless; hosting region: see RUNBOOK) |
| Monitoring | Better Stack (uptime, status page, logs) |
| Hosting | Render (Frankfurt EU) |
| CI/CD | GitHub Actions |
Privacy & security
Everything that remembers needs an account (only the topic learning and the Kartenaufgaben run in the browser without one). The user-facing statement, including every processor, is the in-app Datenschutzerklärung (/privacy).
- Passwordless login: email + one-time code, or the link in the same email (ADR-0064).
- Session: JWT in an httpOnly cookie, never readable by JavaScript (ADR-0012).
- EU hosting on Render in Frankfurt; the Lotsen-Check sends text to Anthropic (US) only on the learner's click and never their identity — what exactly: FEATURES → Lotsen-Check.
- Details: the threat model and its measures in ARCHITECTURE → Threat model; vulnerabilities are reported privately, see SECURITY.md.
Architecture & decisions
This is the beginning of the README. Read the rest at the original. Read the full README ↗
