347b1de555
All checks were successful
Build & Publish Docker Image / build-and-push (push) Successful in 53s
Drei fokussierte Dokumente, damit eine frische Claude-Session direkt weiterarbeiten kann, ohne den gesamten Session-Kontext zu brauchen: - CLAUDE.md (Root): "read me first" — Gotchas, Workflow, No-Gos, Quickstart, Verweise auf die Tiefen-Docs. - docs/ARCHITECTURE.md: Stack, Verzeichnisbaum, Datenfluss (Import, Web-Suche, Confirm/Alert), Design-Entscheidungen, Test-Strategie. - docs/OPERATIONS.md: Deployment-Topologie (Cloudflare → Pi → Traefik → kochwas), Gitea-CI-Pipeline, Traefik-Labels mit Wildcard-Cert, Troubleshooting (TLS, SearXNG-403, Healthcheck, Thumbnail-Cache leeren, Backup), Env-Vars. Die bestehenden Specs und Plans unter docs/superpowers/ bleiben unangetastet — die sind Planungs-Artefakte, nicht Betriebsdoku.
70 lines
4.9 KiB
Markdown
70 lines
4.9 KiB
Markdown
# Kochwas — Hinweise für Claude (Fortsetzung nach Session-Neustart)
|
|
|
|
> **Lies mich zuerst.** Wenn du eine neue Session öffnest und hier weiterarbeitest, steht hier das Wesentliche. Tiefer: `docs/ARCHITECTURE.md` (Code) und `docs/OPERATIONS.md` (Deployment).
|
|
|
|
## Was das ist
|
|
Selbstgehostete Rezept-PWA für die Familie Siegeln. Erreichbar unter `https://kochwas.siegeln.net`. Deutschsprachiges UI, ohne Login, Profile werden per Klick gewählt. Läuft in Docker auf einem Raspberry Pi 5 (arm64).
|
|
|
|
## Wichtigste Gotchas (wiederkehrende Stolpersteine)
|
|
|
|
| Thema | Regel |
|
|
|---|---|
|
|
| **Node-Binding** | `better-sqlite3` ist **synchron** und native — im `Dockerfile` gibt es einen Build-Stage, der das Native-Module explizit für arm64 baut. |
|
|
| **Healthcheck** | Muss `127.0.0.1` verwenden, nicht `localhost`. Node bindet nur IPv4; `localhost` wird oft zu `::1` aufgelöst und der Check schlägt fehl. Traefik filtert unhealthy Container raus → kein Routing, kein ACME. |
|
|
| **SearXNG Bot-Detection** | Bei Requests aus dem Docker-Netzwerk müssen `X-Forwarded-For: 127.0.0.1` und `X-Real-IP: 127.0.0.1` im Header stehen (`src/lib/server/http.ts` `extraHeaders`). Sonst 403. |
|
|
| **Traefik Cloudflare-Token** | Token muss `Edit zone DNS` Berechtigung für `siegeln.net` haben. Expired Tokens → DNS-Challenge failt → Let's-Encrypt-Rate-Limit nach 5 Versuchen in 1 h. |
|
|
| **Wildcard-Cert** | Für neue Subdomains auf siegeln.net sollten die Labels das Wildcard nutzen, nicht per-Host-Cert: `tls.domains[0].main=siegeln.net` + `sans=*.siegeln.net`. |
|
|
| **Migrations** | Werden via Vite `import.meta.glob('./migrations/*.sql', {eager, query:'?raw'})` gebundelt. Neue Migration einfach als `00N_name.sql` ablegen, kein Copy-in-Dockerfile nötig. |
|
|
| **$lib/server in Client** | Svelte-Import aus `$lib/server/*` in einem `.svelte`-Komponenten-Script bricht den Build. Pures JS/TS, das beidseitig funktioniert (z. B. Portionen-Scaler), gehört nach `$lib/`, nicht `$lib/server/`. |
|
|
| **Preview-Bilder** | `recipe.image_path` kann **absolute URL** (Preview-Modus) oder **lokaler Filename** sein. `RecipeView.svelte` prüft mit `/^https?:\/\//i`. |
|
|
|
|
## Dateien, die man typischerweise anfasst
|
|
|
|
- `src/routes/+page.svelte` — Startseite mit Live-Search + Quote
|
|
- `src/routes/+layout.svelte` — Header, mobile expand, Dropdown-Search auf Rezeptseiten
|
|
- `src/routes/recipes/[id]/+page.svelte` — Rezept-Detail mit allen Actions (Rating, Favorit, Cooked, Wunschliste, Kommentar, Umbenennen, Löschen)
|
|
- `src/routes/preview/+page.svelte` — importierte Vorschau vor dem Speichern
|
|
- `src/lib/server/search/searxng.ts` — Web-Suche + Thumbnail-Enrichment + SQLite-Cache
|
|
- `src/lib/server/recipes/importer.ts` — JSON-LD → Recipe, orchestriert Bild-Download
|
|
- `src/lib/server/db/migrations/*.sql` — Schema; bei Änderung immer **neue** Migration statt bestehende bearbeiten
|
|
|
|
## Arbeitsweise (wie wir es machen)
|
|
|
|
- **Terse Antworten auf Deutsch**; Code-Kommentare auf Englisch, sparsam.
|
|
- **Commits** kleinteilig, deutscher Body, englische Zeile, Subject unter 72 Zeichen.
|
|
- **Tests nach jeder Änderung**: `npm test` (vitest) + `npm run check` (svelte-check). Beides muss grün sein, bevor gepusht wird.
|
|
- **Push nach jedem Commit**, außer der Nutzer sagt explizit nein. CI baut dann das arm64-Image und published es nach `gitea.siegeln.net/claude/kochwas:latest`.
|
|
- **Keine Backwards-Compat-Krücken** für nicht-ausgelieferten Code. Direkt refactoren, alte Signaturen raus.
|
|
- **Nie mit `--no-verify`** committen. Wenn ein Hook fehlschlägt, den echten Grund beheben.
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
npm install # erstes Mal
|
|
npm run dev # lokal auf http://localhost:5173
|
|
npm test # volle Vitest-Suite
|
|
npm run check # svelte-check Types
|
|
npm run format # Prettier
|
|
```
|
|
|
|
Lokaler Docker-Test des Prod-Builds:
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml up --build
|
|
```
|
|
|
|
## Was NICHT tun
|
|
|
|
- Keine neuen Top-Level-Docs erzeugen, wenn ein bestehendes Dokument (Specs, Plans, ARCHITECTURE, OPERATIONS) passt.
|
|
- Keine Emojis in Code/Commits — außer UI-Icons (🍽️, ⚙️, 🥘 etc.) sind explizit im UX-Design.
|
|
- Keine `alert()`/`confirm()` — wir haben `alertAction()` / `confirmAction()` in `src/lib/client/confirm.svelte.ts`.
|
|
- Keine hardcoded `localhost` in Healthchecks → `127.0.0.1`.
|
|
- Keinen sensiblen Output in Commits (Cloudflare-Tokens, acme.json).
|
|
|
|
## Offene Themen / Stand
|
|
|
|
Siehe Session-Handoff-Dokumente unter `docs/superpowers/` und dort besonders `session-handoff-2026-04-17.md`. Die Roadmap-Phasen liegen als `docs/superpowers/plans/*.md`. Was als „Later" markiert ist, ist nicht beauftragt.
|
|
|
|
## Auto-Memory (lokal, nicht im Repo)
|
|
|
|
Persönliche Präferenzen / projektspezifische Entscheidungen landen in deinem Auto-Memory unter `~/.claude/projects/C--Users-Hendrik-Documents-projects-kochwas/memory/`. Der aktuelle Index (`MEMORY.md`) hält fest: Deployment-Target, Registry. Bei Bedarf erweitern — nicht in dieser Datei dokumentieren, da sie versioniert ist.
|