Kaffee-Companion für Web, iOS & Android. Siehe docs/ für Markenkern, UX-Konzept, Tech-Konzept und Dev-Plan.
M0–M4 aus docs/04_DEV_PLAN.md sind gebaut — lokal lauffähig als Vite-Dev-Server bzw. installierbare PWA,
DE/EN-Sprachumschaltung, Onboarding, Konto (E-Mail/Passwort + anonym), Datenexport/-löschung, Feedback-Formular.
Für den vollen Funktionsumfang (Wetter, Fotos, Community-Vorschläge, Konten) muss zusätzlich der Worker lokal
laufen — alles funktioniert komplett ohne Cloudflare-Account (Miniflare simuliert D1/R2/KV lokal).
M4 ergänzt: geführtes Onboarding (Methode → Equipment → Bohne → Standort-Opt-in) beim ersten Start;
vollständige DE/EN-Übersetzung mit Sprachumschalter (Einstellungen); Konto-Verwaltung über better-auth
(E-Mail/Passwort + anonyme Geräte-Sessions, siehe unten für Apple/Google); Datenexport (JSON) und
-löschung; Feedback-Formular (landet in D1). Die Moderations-Queue (/moderation, seit M3) ist jetzt an
eine echte, nicht-anonyme Anmeldung gebunden statt offen zu sein.
apps/
web/ React + Vite PWA — die eigentliche App
worker/ Cloudflare Worker (Hono) — API (Wetter, Moderation, Fotos, Feedback, better-auth) + Static-Assets
packages/
core/ Domänen-Logik (Ratio-Mathe, Kompass-Regelwerk mit "Warum", Frische-Kurve) — framework-frei, Golden-Tests
db/ Ein Drizzle-SQLite-Schema (App-Daten + better-auth-Tabellen) für lokale DB und D1, Migrationen
ui/ Design-Tokens (Tailwind-Theme) + geteilte Komponenten (inkl. Chart)
api-client/ Wetter-, Produkt-Moderation-, Foto-Upload- und Feedback-Clients; BLE-Scale-Client folgt in Phase 2
apps/web/src/i18n/ DE/EN-Wörterbücher + React-Context (useT, useLocale)
apps/web/src/auth/ better-auth React-Client + Session-Bootstrap (useEnsureSession)
Voraussetzung: Node ≥ 20, pnpm (corepack enable oder npm i -g pnpm).
pnpm install
pnpm dev:web # startet die Web-App auf http://localhost:5173Für Wetter, Konten, Foto-Upload, Community-Vorschläge und Feedback zusätzlich den Worker lokal starten (in einem zweiten Terminal, kein Cloudflare-Account nötig — Miniflare simuliert die Bindings). Beim allerersten Mal die D1-Migration anwenden und ein lokales Auth-Secret anlegen:
cp apps/worker/.dev.vars.example apps/worker/.dev.vars
# BETTER_AUTH_SECRET in apps/worker/.dev.vars eintragen, z. B.:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
pnpm --filter @kvarn/worker db:migrate:local # einmalig, legt alle Tabellen in der lokalen D1 an
pnpm dev:worker # startet den Worker auf http://localhost:8787Vite proxied /api/* im Dev-Modus automatisch an localhost:8787 (siehe apps/web/vite.config.ts). Ohne
laufenden Worker funktioniert die App weiterhin lokal — Wetter, Konten, Foto-Upload, Community-Vorschläge
und Feedback werden dann einfach übersprungen (nie ein Blocker fürs Brühen).
Der erste Start zeigt automatisch das Onboarding (Methode → Equipment-Suche in ~390 Geräten oder eigenes Gerät → erste Bohne → Standort-Opt-in), danach ist Brühen nutzbar: Parameter (mit Kompass-Vorschlag + "Warum") → Timer → Bewertung → Logbuch & beste Rezepte (Kompass). Sprache, Konto, Datenexport/-löschung und Feedback liegen unter Einstellungen (oben rechts in der App).
pnpm test
pnpm typecheck
pnpm lint
pnpm build- Apple/Google-Sign-in: better-auth ist vorbereitet, aber es sind keine OAuth-Client-Credentials von
Apple/Google hinterlegt (die kann nur der Kontoinhaber der jeweiligen Developer-Programme anlegen). E-Mail/
Passwort und anonyme Sessions funktionieren bereits vollständig. Sobald Credentials vorliegen, in
apps/worker/src/auth.tsalssocialProvidersergänzen. - Kompass-Begründungen sind noch nicht übersetzt:
packages/cores Regelwerk (nextGrindSuggestion) baut seine "Warum"-Sätze fest auf Deutsch zusammen. Bei englischer UI-Sprache erscheint der Kompass-Hinweis auf dem Brühen-Screen daher gemischtsprachig. Sauberer Fix:nextGrindSuggestionauf strukturierte Begründungscodes umstellen und die Sätze inapps/webper i18n formatieren. - Lokale Daten sind nicht an Konten gebunden: Setups/Bohnen/Bezüge bleiben geräte-lokal in IndexedDB, auch nach Anmeldung. Ein echtes Sync/Merge zwischen Geräten ist ein eigenes Vorhaben (Backlog-Epic E6), bewusst nicht Teil von M4.
- AI-Illustrations-Pipeline ohne Credentials:
/api/illustrations/*/generate(Moderation-Screen → Abschnitt "Illustrationen", für Community-Geräte ohne Bild) brauchtGOOGLE_CSE_API_KEY,GOOGLE_CSE_CXundGEMINI_API_KEY(sieheapps/worker/.dev.vars.example). Ohne diese drei Keys antwortet der Endpunkt mit 501 statt zu generieren — Code und Tests sind vollständig, nur die Drittanbieter-Keys fehlen, weil sie nur der Kontoinhaber anlegen kann.
Wichtig: Alle wrangler-Befehle unten mit cd apps/worker ausführen (nicht im kvarn/-Repo-Root — Wrangler
findet dort kein wrangler.toml, sieht aber pnpm-workspace.yaml und bricht mit einem
"application detection... in the root of a workspace"-Fehler ab). Nie --name an einen wrangler-Befehl
anhängen, auch nicht um den Fehler zu umgehen — das legt einen zweiten, unabhängigen Worker an statt den
einen aus apps/worker/wrangler.toml (name = "kvarn-coffee") zu treffen. Genau das ist uns schon einmal
passiert: ein per --name kvarn erzeugter Geister-Worker ohne Routen/Domain, während der echte,
GitHub-verbundene Worker (kvarn-coffee, mit der Domain) die Secrets nie bekam.
- Cloudflare-Account anlegen: https://dash.cloudflare.com/sign-up
cd apps/worker && pnpm dlx wrangler login(Browser-Login).pnpm wrangler d1 create kvarn,pnpm wrangler r2 bucket create kvarn-photos,pnpm wrangler kv namespace create WEATHER_CACHE(weiterhin inapps/worker) — jeweils die zurückgegebene ID inapps/worker/wrangler.tomleintragen.pnpm wrangler secret put BETTER_AUTH_SECRET— eigenen Zufallswert setzen (siehe oben). Optional für die AI-Illustrations-Pipeline zusätzlichpnpm wrangler secret put GOOGLE_CSE_API_KEY,GOOGLE_CSE_CXundGEMINI_API_KEYsetzen (sieheapps/worker/.dev.vars.example).pnpm --filter @kvarn/worker db:migrate:remote— Migrationen auf die echte D1 anwenden.- In Cloudflare: Workers & Pages → Create → Import a repository, das GitHub-Repo
kvarnverbinden (Workers Builds deployt danach bei jedem Push aufmain). Im Projekt unter Settings → Build den Deploy command aufnpx wrangler deploy --config apps/worker/wrangler.tomlsetzen — ohne den--config-Pfad läuftwrangler deployim Repo-Root und schlägt mit demselben "workspace root"-Fehler wie oben fehl, weil Workers Builds vom Monorepo-Root aus deployt. - Sobald eine öffentliche URL/Domain feststeht: in
apps/worker/src/auth.tszutrustedOriginshinzufügen (aktuell nur die lokalen Dev-Origins für den Vite-Proxy).
Details siehe docs/03_TECH_KONZEPT.md und docs/04_DEV_PLAN.md.