diff --git a/README.md b/README.md index da1c9f5..09c7134 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,75 @@ A social platform where pets are the stars. Dogs, cats, birds, horses, rabbits, --- +## System Architecture + +Web and mobile are two clients over the **same** Next.js/tRPC backend and the same Postgres database — there is no separate mobile API. Deployment is asymmetric: web ships via a self-hosted Docker rolling deploy on the NAS, mobile ships via either an EAS native build (Play Store) or an EAS Update OTA push (JS/UI-only changes, no store review). + +```mermaid +flowchart TB + Dev["Dev Machine
git push"] + + subgraph Clients["Clients"] + WebApp["Web App
Next.js, browser (pawfeed.org)"] + MobileApp["Mobile App
Expo / React Native, Android"] + end + + Clerk[("Clerk
Owner auth")] + + subgraph Server["Next.js Server (shared backend)"] + TRPC["tRPC Routers
~20 domain routers"] + CronRoutes["/api/cron/*"] + MuxWebhook["/api/webhooks/mux"] + AdminPanel["/p/[secret]/*
Admin Panel"] + end + + subgraph Data["Data & Media"] + Postgres[("Postgres
Supabase, via Prisma")] + Redis[("Redis
feed fan-out + rate limit")] + Storage["Supabase Storage
pet-avatars, music-tracks"] + Mux["Mux
video transcode / HLS"] + end + + subgraph NAS["Self-hosted NAS (OpenMediaVault)"] + Gitea["Gitea
git remote, :2222"] + DeployCheckout["/Dockers/PawFeed
working tree"] + Replicas["pawfeed-1/2/3
Docker, load-balanced"] + NPM["Nginx Proxy Manager
+ Cloudflare"] + CronJobs["crontab
run-cron.sh, backup-db.sh"] + end + + subgraph MobileDelivery["Mobile Delivery"] + EASBuild["EAS Build
native binary"] + EASUpdate["EAS Update
OTA, JS/UI only"] + PlayStore["Google Play
Closed Testing"] + end + + WebApp --> TRPC + MobileApp --> TRPC + WebApp --> Clerk + MobileApp --> Clerk + + TRPC --> Postgres + TRPC --> Redis + TRPC --> Storage + TRPC --> Mux + Mux --> MuxWebhook --> TRPC + CronJobs -->|"bearer token"| CronRoutes --> TRPC + CronJobs -->|"pg_dump, 30d retention"| Postgres + + Dev -->|"git push"| Gitea -->|"git pull + rolling-deploy.sh"| DeployCheckout --> Replicas --> NPM --> WebApp + + Dev -->|"eas update"| EASUpdate -->|"OTA JS bundle"| MobileApp + Dev -->|"eas build + submit"| EASBuild --> PlayStore -->|"native install/update"| MobileApp +``` + +Notable asymmetries worth remembering: +- Mobile has **no video-story support and no music-overlay support yet** (both web-only today) — see `mobile/PENDING-NATIVE-BUILD.md`. +- `backup-db.sh` talks to Postgres **directly** (`pg_dump` via a throwaway container), bypassing the tRPC layer entirely — it's the one path that isn't "go through the API." +- `AdminPanel` sits inside the same Next.js server/tRPC layer as the public app — gated by a secret path segment *and* a role check, not a separate deployment. + +--- + ## Project Structure ``` @@ -325,6 +394,35 @@ Runs `pg_restore --clean --if-exists --no-owner --no-privileges -j 4` against `D --- +## AI-Assisted Development Workflow + +This project is developed with Claude Code as the primary contributor. The full, living version of this workflow — including the gap analysis against the formal `.claude/rules/ecc/**` process and the open discussion points — lives in `WORKFLOW.md` at the repo root. This section is the durable, contributor-facing summary; update both files together when the process changes. + +**Per change (bugfix / small task):** + +1. Load context (`CLAUDE.md`, `.claude/rules/ecc/**`, stored memories, git status) — automatic, not a manual step. +2. Classify the request (bug report / implementation task / question / deploy action / docs). +3. Root-cause investigation before touching code — read the actual code and, where relevant, the actual production data (DB query, logs) rather than assuming. Search for and **fix twin instances of the same bug pattern automatically**, not just the one reported (e.g. one dark-mode fix in `post-new.tsx` surfaced and fixed the same bug in `story-new.tsx`/`search.tsx` in the same pass) — unless that would itself grow into a new feature, in which case it's flagged instead. +4. Implement, matching the closest existing pattern already in this codebase rather than generic best-practice defaults. +5. Verify: `tsc --noEmit`, `eslint` on changed files, tests where a suite exists for that area. A `git stash`/tool-rerun/`git stash pop` cycle separates pre-existing warnings from newly introduced ones before either is claimed. +6. **Code review before commit** — the `code-review` skill runs against the diff (CRITICAL/HIGH findings get fixed before committing; this is the actually-installed equivalent of the `code-reviewer` agent named in `.claude/rules/ecc/common/agents.md`, which isn't present in this environment's agent roster). +7. Commit with exact paths (never `git add -A` — this repo carries long-lived unrelated uncommitted work from other in-flight sessions) and push. +8. **Automatic deploy/publish, no confirmation needed, once 5 and 6 are clean:** + - Web change (`src/**`) → `./docker/rolling-deploy.sh` on the NAS + - Mobile change (`mobile/**`), pure JS/UI, no new native module → `eas update --branch production --environment production --platform android` + - Anything touching a native module, app version, or `app.json` permission → **not** an OTA case; flagged for a real native build instead +9. Document: `mobile/found.md` gets the root-cause/fix write-up under the reported item; `README.md` gets anything structurally reusable (new scripts, recurring gotchas) so the next session doesn't re-derive it. + +**Per large mobile feature** (new schema + tRPC + UI spanning multiple files — not a single-file fix, even one that touches twin instances): + +1. **Plan first** — via the `Plan` agent / `EnterPlanMode` before any code (the installed equivalent of the `planner` agent referenced in the formal rules). +2. **Own feature branch** (`git checkout -b feature/`), not directly on `main`. Verification and code review (steps 5–6 above) still run per commit on the branch, but the automatic deploy/OTA in step 8 does **not** fire until the branch is merged into `main`. +3. Merge to `main` only once the feature is complete and every commit on the branch is verified + reviewed; the normal automatic-deploy step then applies to the merge commit. + +**Still requires explicit confirmation, no exceptions today:** DB restore/backup execution against the real production database, new NAS infrastructure/cron entries before they go live, and any native mobile build/store submission. + +--- + ## Architecture Notes ### Identity model diff --git a/WORKFLOW.md b/WORKFLOW.md new file mode 100644 index 0000000..26186cb --- /dev/null +++ b/WORKFLOW.md @@ -0,0 +1,157 @@ +# WORKFLOW.md + +Dokumentiert den Ablauf, den ich (Claude Code) in diesem Projekt einhalte, sobald ein Prompt eingeht. Stand: nach der ersten Automatisierungsrunde vom 2026-09-19 — vier Punkte wurden vom Entscheidungs- in den verbindlichen Status überführt (siehe „Beschlossene Automatisierungen" unten). Basis sind weiterhin zwei Quellen, die nicht immer deckungsgleich sind: + +1. **Die formalen Projektregeln** unter `.claude/rules/ecc/**` (Agent-Orchestrierung, TDD, Code-Review-Agenten, 80 %-Testabdeckung, ...) +2. **Das tatsächliche Verhalten** in laufenden Sessions + +Verbleibende Lücken zwischen beidem stehen weiter unten, offen zur Diskussion. + +--- + +## 1. Eingang eines Prompts + +Bei jeder neuen Nachricht lade ich (automatisch, vom Harness bereitgestellt, kein eigener Schritt): + +- `CLAUDE.md` (Projekt-Root + `mobile/` + globale `~/.claude/CLAUDE.md`) +- Alle `.claude/rules/ecc/**`-Dateien, die für den Kontext relevant sind (common + web + react + typescript + ...) +- Gespeicherte **Memories** (`~/.claude/projects/.../memory/*.md`) — projektspezifisches Wissen, das nicht im Code steht (z. B. "NAS hat kein Node im PATH", "nie `git add -A`") +- Git-Status-Snapshot (Branch, offene Änderungen, letzte Commits) + +Ich lese das als Kontext, nicht als neue Anweisung — es sei denn, der Prompt selbst bezieht sich darauf. + +## 2. Einordnen der Anfrage + +| Art der Anfrage | Beispiel | Reaktion | +|---|---|---| +| Bug-Report / Fehleranalyse | "die Notification zeigt PET_SUGGESTION an" | Root-Cause suchen, bevor irgendwas geändert wird | +| Konkreter Umsetzungsauftrag | "richte den NAS-Cron ein" | Direkt umsetzen, Zwischenstände kurz melden | +| Frage / Erklärung | "haben wir eine Backup-Funktion im Adminpanel?" | Antworten, ggf. mit Code-Beleg — nicht ungefragt bauen | +| Deploy-/Produktions-Aktion außerhalb der beschlossenen Automatisierung | z. B. DB-Restore | Nur nach expliziter Bestätigung ausführen | +| **Großes Mobile-Feature** (neu, nicht Bugfix/kleiner Fix) | z. B. Story-Musik-Overlay, Pet-Suggestion-Notifications | **Zuerst Planner, dann eigener Feature-Branch** — siehe Abschnitt 9a | +| Doku-/Meta-Auftrag | dieses Dokument hier | Direkt umsetzen | + +Bei Unklarheit: lieber die naheliegendste Lesart umsetzen und den Punkt kurz benennen, als mit einer Rückfrage blockieren — außer die Aktion ist riskant/schwer umkehrbar (siehe 6). + +## 3. Root-Cause-Untersuchung (bei Bugs) + +Bevor ich etwas ändere: + +1. **Code lesen**, nicht raten — betroffene Datei(en) über Grep/Glob/Read finden, nicht über Vermutung +2. **Bei Diskrepanz zwischen Code und beobachtetem Verhalten**: prüfen, ob der Code überhaupt in Produktion läuft (Beispiel aus der Praxis: OTA-Update war 6 Tage nicht gepublished → Code war korrekt, kam aber nie an) +3. **Datenbank-Fakten statt Annahmen**: bei Verdacht auf Datenproblem lieber direkt gegen die echte DB prüfen (via NAS-Container) als zu spekulieren +4. **Denselben Fehler an anderer Stelle suchen** — gezielt per Grep nach demselben Muster in verwandten Dateien. **Seit 2026-09-19 beschlossen: gefundene Zwillings-Instanzen werden automatisch mitgefixt**, nicht nur gemeldet (Beispiel: `story-new.tsx`/`search.tsx` hatten denselben Dark-Mode-Bug wie `post-new.tsx`). Ausnahme: der Fix wäre selbst ein größeres, eigenständiges Vorhaben (neues Feature, Architekturänderung) statt einer echten Wiederholung desselben Musters — dann melden + Rückfrage statt automatisch ausweiten. + +## 4. Umsetzung + +- **Pattern-Matching mit bestehendem Code**: neue/geänderte Screens nach dem Muster einer bereits funktionierenden, vergleichbaren Datei im selben Projekt bauen (z. B. `milestone-new.tsx` als Vorlage für den `post-new.tsx`-Fix), nicht nach generischem Best-Practice-Wissen +- **Kleinstmöglicher Diff** für den gemeldeten Fehler, plus die in Schritt 3.4 automatisch mitgefixten Zwillings-Instanzen +- Rules aus `.claude/rules/ecc/**` (Naming, Dateigröße, Immutability, Fehlerbehandlung etc.) fließen beim Schreiben ein, ohne dass ich das jedes Mal einzeln abhake + +## 5. Verifikation vor "fertig" + +1. `npx tsc --noEmit` (bzw. `npx tsc --noEmit --incremental` je nach Hook-Konfiguration) +2. `npx eslint ` +3. Bei Unsicherheit, ob eine Lint-/Type-Warnung neu ist: `git stash` → Tool erneut laufen lassen → `git stash pop`, um "vorbestehend vs. neu eingeführt" sauber zu trennen, statt das zu behaupten +4. Tests (`npx vitest run`), wenn im Umfeld der Änderung vorhanden — bei mobile-only-UI-Fixes bisher nicht Teil der Suite (kein RN-Testsetup in `mobile/`, nur `src/__tests__/` auf Web-Seite) + +Kein Schritt wird als "sauber" gemeldet, ohne dass er tatsächlich ausgeführt wurde. + +## 6. Code-Review vor Commit (neu, seit 2026-09-19) + +Nach Schritt 5, vor jedem Commit: Review des Diffs über die `code-review`-Skill (Findings-Format wie in `.claude/rules/ecc/common/code-review.md` vorgesehen — CRITICAL/HIGH/MEDIUM/LOW). + +> **Anmerkung zur Umsetzung:** `.claude/rules/ecc/common/agents.md` referenziert dafür einen `code-reviewer`-**Agenten** aus `~/.claude/agents/`. Dieser Agent ist in der aktuell verfügbaren Agent-Liste dieser Umgebung nicht installiert (nur pentest-bezogene Agents + `general-purpose`/`Explore`/`Plan`). Die tatsächlich verfügbare, gleichwertige Instanz ist die **`code-review`-Skill** — die kommt hier zum Einsatz. Falls der `code-reviewer`-Agent künftig installiert wird, übernimmt er diese Rolle 1:1. + +Ablauf: +- **CRITICAL/HIGH-Befund** → beheben, bevor committed wird (kein Override ohne Rückfrage) +- **MEDIUM/LOW** → beheben, wenn der Aufwand gering ist, sonst im Commit/`found.md` vermerken statt zu blockieren +- **Keine Befunde** → direkt weiter zu Schritt 7 + +## 7. Bestätigung vor riskanten/schwer umkehrbaren Aktionen + +**Ohne Rückfrage** (laut Memory `feedback_auto_commit_tested_changes`: *"tested/positive changes get auto commit+push+found.md update, no asking"* — seit 2026-09-19 erweitert um die Deploy-Automatisierung aus Schritt 9): +- Commit + Push von verifiziertem, code-reviewtem Code (exakte Pfade stagen, nie `git add -A`) +- `found.md`-Einträge mit Analyse/Fix-Vermerk ergänzen +- Lesende Diagnose-Befehle (DB-Query, Log-Ansicht, `crontab -l`, ...) +- **Web-Rolling-Deploy**, sobald ein Web-Fix committed + verifiziert (Schritt 5) + code-reviewt (Schritt 6) ist +- **Mobile-OTA-Publish**, sobald ein reiner JS/UI-Fix committed + verifiziert + code-reviewt ist + +**Mit expliziter Rückfrage** (weiterhin): +- Restore/Backup-Ausführung gegen die echte Produktions-DB +- Neue Infrastruktur/Cron-Einträge auf der NAS, bevor sie aktiv geschaltet werden +- Jede native Mobile-Änderung (neuer nativer Build/Store-Submission) — kein OTA-Fall +- Jede Aktion, die der Auto-Mode-Classifier selbst als "Production Deploy" blockiert — siehe Caveat in Schritt 9 + +Bei "riskant" zähle ich: nicht rückgängig machbar, betrifft echte Nutzer/echte Daten, oder verändert etwas außerhalb des Git-Repos (NAS, externe Dienste) **und** ist nicht durch die Deploy-Automatisierung aus Schritt 9 bereits abgedeckt. + +## 8. Dokumentation + +- **`found.md`** (mobile Tester-Feedback-Log): Antwort/Root-Cause/Fix direkt unter den gemeldeten Punkt schreiben, Format `- [x] ` + eingerückter `→`-Analyse-Text +- **`README.md`** (Projekt-Root, nicht `mobile/`): strukturelle Erkenntnisse, die über den Einzelfall hinaus relevant sind (neue Scripts, wiederkehrende Stolperfallen, dieser Workflow) — Ziel: nächste Session muss dasselbe Problem nicht neu lösen +- **Keine Doku für Dinge, die nur diese Konversation betreffen** oder die der Code/Git-Verlauf schon selbsterklärend zeigt + +## 9. Git, Deploy und OTA-Publish — jetzt eine durchgehende Kette + +Seit 2026-09-19 hängen Commit → Deploy/Publish direkt aneinander, ohne Zwischen-Rückfrage, **sofern** Schritt 5 (Verifikation) und Schritt 6 (Code-Review) sauber durchlaufen sind: + +1. **Commit**: `: ` + ausführlicher Body (Root Cause, Warum-nicht-anders, Testergebnis) + Attribution-Zeile. **Nie `git add -A`** — immer exakte Pfade (siehe Memory `project_repo_has_stray_uncommitted_work`). +2. **Push** direkt danach, kein Sammel-Commit über mehrere Themen. +3. **Automatischer Deploy/Publish, abhängig vom Änderungsort:** + - Änderung unter `src/**` (Web) → `./docker/rolling-deploy.sh` auf der NAS + - Änderung unter `mobile/**`, rein JS/UI, kein neues natives Modul → `eas update --branch production --environment production --platform android` + - Änderung, die ein natives Modul/eine App-Version/`app.json`-Permission betrifft → **kein** automatischer Publish, stattdessen Rückfrage (das ist kein OTA-Fall, siehe `mobile/PENDING-NATIVE-BUILD.md`-Konvention) + - Reine Doku-/Script-Änderung ohne Laufzeitwirkung auf App-Code (z. B. dieses Dokument, `docker/backup-db.sh`) → kein Deploy nötig + +**Technischer Vorbehalt:** Der Auto-Mode-Classifier des Harness blockt bestimmte Bash-Kommandos aktiv als "Production Deploy" und verlangt dann trotzdem eine manuelle Bestätigung — unabhängig davon, was dieses Dokument vorsieht. Dieses Dokument beschreibt meine **Absicht**, den Deploy ohne Rückfrage anzustoßen; ob das technisch auch ohne Prompt durchläuft, hängt von der Classifier-Konfiguration ab, die ich nicht selbst ändern kann. Falls der Classifier weiter blockt, versuche ich den Deploy trotzdem sofort (statt vorher zu fragen) und der Prompt kommt dann vom Harness, nicht von mir aus Vorsicht. + +- **DB-Änderungen** bleiben unverändert manuell/mit Rückfrage: `prisma db push` ausschließlich über einen Wegwerf-Container auf der NAS, nie `migrate dev`/`reset` (siehe Memory `project_nas_db_tooling`). + +## 9a. Ausnahme: Große Mobile-Features → Planner + eigener Branch (neu, seit 2026-09-19) + +Die durchgehende Commit→Deploy-Kette aus Schritt 9 gilt für **Fixes und kleine Änderungen**. Für ein **großes neues Mobile-Feature** gilt stattdessen: + +1. **Erst Planner, dann Code.** Bevor eine Zeile geschrieben wird, läuft die Anforderung durch eine Planungsphase (`Plan`-Agent bzw. `EnterPlanMode` — das ist die in dieser Umgebung tatsächlich installierte Entsprechung von `.claude/rules/ecc/common/agents.md`s `planner`-Agent, der hier nicht verfügbar ist). Ergebnis: ein abgenommener Plan, bevor implementiert wird — wie bereits bei den Features "Pet-Suggestion-Notifications" und "Story-Musik-Overlay" praktiziert (Plan unter `~/.claude/plans/`). +2. **Eigener Feature-Branch statt direkt auf `main`**: `git checkout -b feature/` vor dem ersten Commit des Features. Alle Zwischen-Commits des Features laufen auf diesem Branch. +3. **Die Automatik aus Schritt 9 (OTA-Publish/Rolling-Deploy ohne Rückfrage) greift auf dem Feature-Branch nicht.** Verifikation (5) und Code-Review (6) laufen trotzdem pro Commit mit — nur der automatische Publish/Deploy bleibt aus, solange der Branch nicht auf `main` ist. +4. **Merge nach `main`** erst nach Abschluss des Features (alle Teilschritte fertig, verifiziert, code-reviewt) — danach greift die normale Automatik aus Schritt 9 für den Merge-Commit. + +**Was als "groß" zählt** (Beispiele aus bisherigen Sessions): neues Feature mit eigenem DB-Schema-Zusatz, neuer Screen/Flow, mehrere zusammenhängende Dateien über mehrere Domains (DB + tRPC + UI). **Was NICHT darunterfällt** (bleibt bei der normalen Kette aus Schritt 9): Einzeldatei-Bugfixes, auch wenn dabei mehrere Zwillings-Instanzen mitgefixt werden (Schritt 3.4) — das sind Fixes, keine neuen Features. + +## 10. Abschlussmeldung + +- Auf Deutsch, knapp, ohne Wiederholung des bereits Gesagten +- Faktentreu: was wirklich getestet wurde vs. was nur plausibel ist, wird nicht vermischt +- Offene Punkte/Restrisiken werden benannt statt verschwiegen +- Wenn automatisch deployed/published wurde: das explizit im Ergebnis nennen (nicht stillschweigend voraussetzen, dass der Nutzer es an den Log-Zeilen erkennt) + +--- + +## Beschlossene Automatisierungen (2026-09-19) + +Diese vier Punkte sind nicht mehr zur Diskussion offen, sondern aktiver Bestandteil der Schritte oben: + +| # | Automatisierung | Bedingung | Umgesetzt in | +|---|---|---|---| +| 1 | OTA-Publish ohne Rückfrage | Typecheck + Lint sauber, Code-Review ohne CRITICAL/HIGH, reiner JS/UI-Fix | Schritt 9 | +| 2 | Code-Review-Lauf vor jedem Commit | Immer, nach Verifikation | Schritt 6 | +| 3 | Verwandte Bug-Instanzen automatisch mitfixen | Echtes Wiederholungsmuster, kein neuer Scope | Schritt 3.4 | +| 4 | Web-Rolling-Deploy automatisch anstoßen | Web-Fix committed + verifiziert + code-reviewt | Schritt 9 | +| 5 | Große Mobile-Features: Planner vorschalten + eigener Feature-Branch statt direkt auf `main` | Nur "groß" (siehe Definition in 9a), nicht für Einzeldatei-Fixes | Schritt 9a | + +## Verbleibende Lücke zwischen formalen Regeln und gelebter Praxis + +| Formale Regel (`.claude/rules/ecc/**`) | Tatsächliche Praxis | +|---|---| +| `planner`-Agent für Planung vor jeder komplexen Änderung | Für **große Mobile-Features** jetzt via `Plan`-Agent/`EnterPlanMode` übernommen (Schritt 9a); für Web-Features weiterhin offen | +| `tdd-guide`-Agent, Test-First (RED→GREEN→REFACTOR), 80 % Coverage | Kein neuer Test für Mobile-UI-Fixes (keine RN-Testinfrastruktur vorhanden) — nur Typecheck/Lint/Code-Review als Gate | +| Parallele Multi-Agent-Recherche (GitHub-Suche, Context7, Exa) vor jeder Neuimplementierung | Nicht angewendet — direkt im bestehenden Code nach Mustern gesucht | +| Explizite Checkliste (Security/Quality) vor "fertig" | Implizit über Typecheck/Lint/Code-Review, nicht als abgehakte Liste | + +`code-reviewer`-Agent/-Skill ist mit der Automatisierung oben aus dieser Tabelle raus — nicht mehr offen. + +## Noch offen (zur Diskussion) + +- **Tests verpflichtend** für mobile UI-Fixes einführen? Aktuell keine RN-Testinfrastruktur vorhanden — wäre selbst ein Vorprojekt (Jest/RNTL-Setup, erste Tests), bevor TDD für Mobile überhaupt greifen kann. +- **`planner`-Agent (bzw. `Plan`/`EnterPlanMode`) auch für große Web-Features** vorschalten? Für Mobile ist das seit 2026-09-19 entschieden (9a), für Web noch offen. +- **Multi-Agent-Recherche** (GitHub/Context7/Exa) vor Neuimplementierungen einführen, oder bei diesem Projektstand (etabliertes Codebase-Pattern-Matching reicht meist) verzichtbar?