chore(app): TS app skeleton, docker compose and verify commands

[Fluory]

Warum

Fixes #3 · Teil von Epic #2. Basis ist main (Fundament #20 ist gemergt). Alle folgenden Issue-PRs des Nachtlaufs stapeln auf diesem Branch.

Arbeitsstand

• Ziel: Das leere System wird lauffähig und prüfbar: docker compose up startet Postgres, SeaweedFS, setup, web und einen No-op-worker; verify:changed / verify / verify:full existieren und laufen in der CI.
• Nicht-Ziele: Auth, RLS-Policies, AI-Service, pg-boss, UI über eine Platzhalterseite hinaus.
• Erledigt: alles aus dem Testplan; frischer Review eingearbeitet (Kommentar); pnpm verify lokal grün; CI check + compose-smoke grün auf dba107f.
• Offen: menschliche Freigabe (Migration, Infra/CI, öffentlicher Endpunkt) und Entscheidung „Rollen im Init-Skript".
• Annahmen: siehe Impact Manifest „Offene Annahmen".
• Nächster kleinster Schritt: Review durch den Orchestrator; danach Merge, dann feat(identity,tenancy): invite-only login, companies and forced RLS #31 zeigt auf main.

Was ist passiert (Klartext)

Das Projekt hat jetzt ein lauffähiges technisches Gerüst. Ein Befehl (docker compose up) startet die Datenbank, den Dokumentenspeicher, einen einmaligen Einrichtungsschritt (Datenbankstruktur anlegen, privaten Speicherbereich anlegen), die Webanwendung und den Hintergrund-Worker. Unter /api/health sieht man, ob Datenbank und Speicher erreichbar sind – ohne dabei Adressen oder Benutzernamen zu verraten.

Die Datenbank kennt zwei Rollen: eine, die die Struktur ändern darf (nur beim Einrichten), und eine für den laufenden Betrieb, die die spätere Mandantentrennung (Row-Level Security) nie umgehen kann. Die Einrichtung bricht ab, wenn diese Rollen falsch konfiguriert sind.

Außerdem gibt es jetzt die Prüfbefehle, die jeden weiteren PR absichern, und eine automatische Architekturprüfung: Module dürfen nur über ihre öffentliche Eingangsdatei miteinander sprechen, und nur die Datenbankschicht darf die rohe Datenbankverbindung benutzen.

Infrastruktur-/CI-Änderung (braucht menschliche Freigabe): Die CI startet jetzt PostgreSQL und SeaweedFS über compose.yaml, damit die Integrationstests gegen echte Dienste laufen, und ein neuer Job compose-smoke baut das Image und prüft docker compose up → /api/health, aber nur wenn sich Dockerfile oder Compose-Datei ändern. Bestehende Prüfschritte wurden nicht verändert.

Plan-Pflicht (SYSTEM.md §4)

• Kein Auslöser – keine Modulgrenze, öffentliche API, Migration, Auth/Rechte, kein Zahlungs-/Daten-/Infrapfad, höchstens zwei Module, keine Architekturvarianten, umkehrbar
• Auslöser zutreffend – Impact Manifest ausgefüllt (Plan vor Code)

Impact Manifest

• Betroffene Module: Root-Konfiguration, src/app (Layout, Platzhalterseite, api/health, Composition Root _server), src/db, src/config, src/features/*/index.ts, storage, observability, jobs (No-op-Worker), compose.yaml, Dockerfile, docker/postgres/init/, .env.example, CI.
• Schnittstellen / Datenänderungen: neuer Endpunkt GET /api/health; zwei DB-Rollen (app_owner, app_rw); erste Migration legt Schema app + Rechte an.
  • GET /api/health → 200 {"status":"ok","checks":{"database":"ok","storage":"ok"}}; bei Ausfall 503 mit Namen der Prüfung (database, storage, config), ohne Fehlerdetails. Vertrag: docs/technical/api.md.
  • Migration 0000_app_schema: prüft Rollen (kein Superuser, kein BYPASSRLS, keine geerbten Owner-/Bypass-Rollen, läuft als app_owner), CREATE SCHEMA app AUTHORIZATION app_owner, USAGE für app_rw ohne CREATE, Default-Privileges (DML auf Tabellen, Sequenzen) für app_rw.
• Akzeptanzkriterien: die aus chore(app): TS app skeleton, docker compose and verify commands #3, mit zwei offengelegten Anpassungen (siehe unten „Abweichungen").
• Testplan: Unit (test-first) für Health-Aggregation und Config; Integration gegen echtes Postgres + SeaweedFS (Health 200/503, Rolleneigenschaften, Schema-Rechte, Rollen-Guard); Architekturtest mit Fixtures (Deep-Import relativ und per @/, roher DB-Client, eigene DB-Verbindung im Feature werden abgelehnt); Compose-Smoke in CI.
• Verifizierte Fakten: npm 2026-09-22: next 16.3.6, typescript 6.0.3 (TS 7 wegen typescript-eslint-Peer ausgeschlossen), eslint 9.39.5, vitest 5.0.1, drizzle-orm 0.45.3, drizzle-kit 0.31.11, pg 8.23.0, dependency-cruiser 18.4.0, @aws-sdk/client-s3 3.1138.0, zod 4.6.5, tsx 4.23.15 (MIT, Node ≥ 18); SeaweedFS 4.47 lehnt falsche S3-Secrets mit 403 ab (Integrationstest); eslint-config-next 16 exportiert Flat-Config-Arrays; pnpm legt .bin/tsx als Shell-Shim an → im Image node …/tsx/dist/cli.mjs.
• Offene Annahmen: keine mehr zum Image – lokal nicht baubar (Docker Hub 429), aber durch den CI-Job compose-smoke bewiesen.
• Nicht-Ziele: Auth, RLS, AI-Service, pg-boss, UI.
• Risiken und Rollback: neue Dependencies (Supply-Chain) → pnpm audit --audit-level high in verify + Lockfile; Rollback per Revert-PR, lokal docker compose down -v (docs/technical/operations.md).

Abweichungen von den Akzeptanzkriterien (offengelegt)

1. Rollen entstehen im Init-Skript, nicht in der Migration. Sonst stünden Passwörter im Repo oder die Migration bräuchte Superuser-Rechte. Die Migration prüft die Rollen und bricht sonst ab; außerhalb Docker legt ein Operator die Rollen einmalig an (operations.md). → decision-needed für den Orchestrator (Morgenbericht).
2. pg-boss kommt erst mit feat(intake): upload a request and enqueue processing atomically #5/feat(jobs,extraction): process requests in the worker with retries and visible errors #7 (Worker ist hier No-op) – keine Dependency auf Vorrat.

Neue Dependencies (Begründung)

Paket	Version	Lizenz	Warum
next, react, react-dom	16.3.6 / 19.3.0	MIT	App-Framework laut ADR-0001 D1
drizzle-orm, drizzle-kit, pg	0.45.3 / 0.31.11 / 8.23.0	Apache-2.0 / MIT	ORM + SQL-Migrationen laut D3
@aws-sdk/client-s3	3.1138.0	Apache-2.0	S3-API laut D5
zod	4.6.5	MIT	Konfigurationsvalidierung
tsx	4.23.15	MIT	führt Worker und Deploy-Schritt aus den TS-Quellen aus (Pfad-Aliasse; Node-Type-Stripping löst @/ nicht auf)
vitest, dependency-cruiser, eslint 9, eslint-config-next, typescript 6.0.3	s. o.	MIT	Tests, Architekturprüfung, Lint, Typen

Geändert

• package.json, pnpm-lock.yaml, tsconfig.json, eslint.config.mjs, next.config.ts, vitest.config.ts, .dependency-cruiser.cjs, drizzle.config.ts: Toolchain und Prüfbefehle.
• src/app/: Layout, Platzhalterseite, api/health/route.ts, _server/runtime.ts (Pool + Storage-Client, lazy).
• src/db/: Client, Migrator, Schema-Stub, Migration 0000_app_schema.sql.
• src/features/*/index.ts: Modul-Skelette laut Architekturkarte; storage (S3-Adapter: ping, ensureBucket), observability (Health).
• src/setup.ts (Deploy-Schritt: Migrationen + Bucket, Retry nur bei transienten Fehlern), src/worker.ts (No-op).
• compose.yaml (+ setup, web, worker), Dockerfile, .dockerignore, .env.example, scripts/verify-changed.sh.
• .github/workflows/ci.yml: Postgres + SeaweedFS vor pnpm verify; Job compose-smoke.
• Tests: tests/integration/* (Health, Migration, Rollen-Guard), tests/architecture/dependency-rules.test.ts + Fixtures.
• Doku: AGENTS.md (Fundament-Hinweis entfernt), README, Architekturkarte, docs/technical/operations.md, docs/technical/api.md, CHANGELOG.

Nachweis (SYSTEM.md §11)

• verify:changed: grün
• verify: grün – lokal (Node 24.21, PostgreSQL 17 + SeaweedFS 4.47): lint, typecheck, 14 Unit + 8 Integrationstests, depcruise 0 Verstöße, next build, pnpm audit --audit-level high (0 high); CI check grün: https://github.com/Fluory/RequestFlow/actions/runs/35824279604
• verify:full / E2E-Spec: nicht betroffen (entspricht verify, bis feat(review): review fields beside their source, correct, approve or reject #8 den Playwright-Smoke bringt)
• Manueller Prüfnachweis: docker compose up --build → curl /api/health → 200 im CI-Job compose-smoke (grün, gleicher Run); lokal zusätzlich Standalone-Server → /api/health 200, pnpm setup:deploy, pnpm worker startet/stoppt sauber.
• Frischer Review (P1 vor Ready-for-review; Architektur/API/DB immer): chore(app): TS app skeleton, docker compose and verify commands #21 (comment) – alle Befunde behoben

Doku-Entscheidung (genau eine)

• Keine langlebige Doku betroffen – Begründung: –
• Doku betroffen und im selben PR aktualisiert:
  • Produktdoku (P0: README): README.md (Getting started)
  • Technische Doku: docs/technical/operations.md (Start/Stopp/Rollback, Rollen außerhalb Docker), docs/technical/api.md (Health-Vertrag), AGENTS.md (Befehle)
  • Architekturkarte: docs/technical/architecture.md (Modulstatus, app-Zeile, DB-Rollen)
  • ADR: –
  • CHANGELOG [Unreleased] (sichtbares Feature oder Verhalten – im selben PR, nie „später")

Entferntes oder Umbenanntes: docs/ + README gegrept, Treffer bereinigt: Fundament-Hinweis in AGENTS.md und README-Status ersetzt

Dateigrößen und neue Bausteine (SYSTEM.md §7)

Dateien über 500 Zeilen im Diff (Ausnahmen: generierter Code, Lockfiles, Fixtures, Migrationen, Schemas, Ressourcen, Doku, Konfiguration):

• keine
• bewusst belassen – Begründung: –
• im selben PR nach fachlicher Verantwortung geteilt
• Folge-Issue –

Über 800 Zeilen mit neuer Fachlogik oder über 1000 Zeilen (P1/P2): nicht betroffen

Neue Shared-Komponente, Utility-Datei, Adapter oder fachlicher Service:

• nein
• ja – gesucht nach: vorhandenem Code im Repo und Modulen der Architekturkarte; gefunden: nichts – storage (S3-Adapter) und observability (Health) sind in der Karte vorgesehen und entstehen hier erstmals

Subagent-Einsätze

• Hintergrund-Agent (gleiches Modell) baut parallel den Python-AI-Service für feat(ai-service): stateless extraction service with grounding verifier #6 in einem eigenen Worktree (nicht in diesem PR).
• Frischer Review: unabhängiger Subagent nach .claude/skills/review-pr/SKILL.md, read-only (2 Läufe).

Risiken / offene Punkte

• docker compose up lokal nicht ausführbar (Docker Hub 429) – Beweis über CI-Job compose-smoke (grün).
• Offene Entscheidung: Rollen im Init-Skript statt in der Migration (s. Abweichungen).

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01DJ5vaKvTYiMvdngT4d3xo1

[Fluory]

Übergabe

Status: WIP – übergeben an die Cloud-Implementierungs-Session (Nachtlauf 2026-09-22/23)
Erledigt: Plan (Impact Manifest); Toolchain gepinnt (TS 6.0.3, ESLint 9.39.5, Next 16.3.6, Vitest 5.0.1, Drizzle 0.45.3); observability/health.ts (4 Unit-Tests) und config/env.ts (5 Unit-Tests) test-first; compose.yaml (Postgres 17.11 + SeaweedFS 4.47) und docker/postgres/init/01-roles.sh, lokal verifiziert: app_owner/app_rw ohne Superuser/BYPASSRLS; SeaweedFS antwortet mit 403 auf ein falsches Secret.
Offen: ESLint-Config, Next-App (layout, Platzhalterseite, api/health-Route mit DB- und Storage-Check), src/db (Client, Drizzle-Config, erste Migration: Schema app + Grants für app_rw), Bucket-Anlage (idempotent), Modul-Skelette + dependency-cruiser inkl. Negativtest, No-op-Worker, Dockerfile + web/worker in Compose, .env.example, scripts/verify-changed.sh, CI mit Postgres + SeaweedFS für Integrationstests, AGENTS.md-Fundamenthinweis entfernen, Architekturkarte/README.
Nächster Schritt: Integrationstest (rot) für /api/health gegen Compose-Postgres + SeaweedFS.
Risiko: keins bekannt; Tests grün (9/9).

[Fluory]

Frischer Review (review-pr, unabhängiger Subagent) – Befunde und Auflösung

Review lief read-only gegen den Branch-Stand; zwei Durchläufe (der erste fand einen Blocker im Compose-Pfad, der zweite prüfte den Fix). Auflösung in Commit dba107f (plus 6aec57e, b3b3c03 für den Compose-Pfad).

#	Befund	Auflösung
Blocker (1. Lauf)	compose-smoke rot: node node_modules/.bin/tsx ist bei pnpm ein Shell-Shim	behoben – node node_modules/tsx/dist/cli.mjs; compose-smoke jetzt grün
Important	Startup-Race: setup lief, bevor SeaweedFS antwortete	behoben – begrenzte Wiederholung (30 × 2 s) nur für Verbindungsfehler
Important	compose-smoke grün noch nicht belegt	erledigt – check + compose-smoke grün auf dba107f
Important	depcruise: Features konnten @/db importieren und selbst eine Verbindung öffnen; _server-Ausnahme unnötig	behoben – Regel no-db-connection-in-features (nur Typ-Importe erlaubt), Ausnahme entfernt, Fixture + Negativtest
Important	Health-Route loggte Konfigurationsfehler nicht, obwohl operations.md das zusagt	behoben – Log nennt Variablennamen (nie Werte)
Note	Retry auch bei dauerhaften Fehlern (Rollen-Guard, falsche Credentials)	behoben – nur transiente Fehler werden wiederholt
Note	Rollen-Guard der ersten Migration ohne Test; geerbte Rollen nicht geprüft	behoben – Integrationstest führt den Guard als app_rw aus; Guard prüft zusätzlich pg_auth_members
Note	Health-Vertrag nur im PR; kein Rate Limit	behoben – docs/technical/api.md; Rate Limit/Cache vor öffentlicher Bereitstellung (Showcase #19) dokumentiert
Note	kein not-to-unresolvable, keine Alias-Fixture	behoben – Regel + @/-Fixture mit Negativtest
Note	Rollen außerhalb Docker undokumentiert; verify:changed versprach „format"	behoben – operations.md-Abschnitt; AGENTS.md-Formulierung korrigiert (ESLint inkl. Stilregeln, kein separater Formatter)

Offen für den Menschen: Rollen entstehen im Init-Skript statt in der Migration (Abweichung vom Akzeptanzkriterium, begründet) – decision-needed im Morgenbericht. Verdict des Reviewers: mergebar nach menschlicher Freigabe (Migration, Infra/CI, öffentlicher Endpunkt).

---

Generated by Claude Code