docs: rewrite CLAUDE.md for full product spec and Postgres stack

Replaces the generic React/Vite/SQLite scaffold description with the actual Deklarix product spec: what it does, the two-stage extract/rules principle, the Postgres-based stack and cmd/deklarix structure, data model, evidence chain, legal guardrails (UWG, Versicherungsaufsicht, BRAO), QA via the golden-test suite, and the DATABASE_URL/test-system split for scripts/test.sh. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-27 00:51:48 +02:00
parent 667343fa81
commit e929e5bf26
1 changed files with 190 additions and 38 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,16 +1,86 @@
 # Deklarix

-> Projekt für deklarix.de und deklarix.com
+> Prüfung und Nachweis für Werbe-Content. Pre-Publish-Kennzeichnungsprüfung
+> und revisionssichere Archivierung für Creator, Agenturen, Marken und
+> Kanzleien. `deklarix.de` / `deklarix.com`
+
+---
+
+## Was das Projekt ist
+
+Drei Funktionen, mehr nicht:
+
+1. **Pre-Publish-Prüfung** — Caption, Standbild und Vertragslage rein,
+   Risikobewertung mit konkreten Korrekturvorschlägen raus.
+2. **Beweissicherung** — jeder veröffentlichte Beitrag wird mit Hash und
+   Zeitstempel archiviert: Screenshot, Caption, sichtbare Kennzeichnung,
+   verknüpfter Vertrag, Briefing.
+3. **Verantwortungsmatrix** — wer hat was vorgegeben, wer hat freigegeben,
+   wer schuldet welche Prüfung (Creator / Agentur / Marke).
+
+**Wer nutzt es, wer zahlt:** Creator nutzen es täglich, zahlen wenig
+(Reichweite/Referenz). Agenturen und Marken zahlen richtig — sie haften
+über § 8 Abs. 2 UWG mit und brauchen Freigabe-Workflow plus
+Nachweisarchiv. Kanzleien lizenzieren Deklarix als Whitelabel für ihre
+Mandanten (zahlen für Software, nicht für Mandantenzugang); das
+Kanzlei-Verzeichnis im Produkt bleibt kostenlos.
+
+**Rollen von Anfang an.** Eine Submission gehört nicht einem Nutzer,
+sondern hat Beteiligte mit Rollen (`creator`, `agentur`, `marke`,
+`kanzlei`). Alle vier existieren im Datenmodell ab dem ersten Commit.
+
+**Kein Demo-Shortcut.** Es wird direkt produktionsreif entwickelt —
+keine reduzierte Zwischenstufe mit manuell eingetragenen Daten oder ohne
+Login als Selbstzweck.
+
+---
+
+## Kernprinzip: das Modell entscheidet nicht
+
+**Das LLM extrahiert Fakten. Das Regelwerk in Go fällt das Urteil.**
+
+- **Stufe 1 — Extraktion (Claude API):** Eingabe Caption plus Bild/Video,
+  Ausgabe striktes JSON (Plattform, Gegenleistung, Kennzeichnung
+  vorhanden/Kanal/Wortlaut/Position, Produktkategorie, Verlinkungen, ...).
+  Ist die Extraktion unsicher, liefert sie `unklar` — nie eine geratene
+  Bewertung.
+- **Stufe 2 — Bewertung (Go, deterministisch):** Regelwerk als
+  versionierte YAML-Dateien (`rules/`). Jedes Finding referenziert
+  Regel-ID und Version (z. B. `WK-004 v3`). Regeln sind
+  plattformunabhängig — UWG/MStV gelten überall gleich, nur
+  Darstellungsdetails unterscheiden sich; die gehören in
+  Regelbedingungen/Extraktion, nie in separate Regelsätze pro Plattform.
+
+**Absolute Regel:** Das Modell nennt niemals selbst Normen, Urteile oder
+Randnummern. Fundstellen stehen ausschließlich in den kuratierten
+YAML-Regeln. Eine halluzinierte Fundstelle ist in diesem Markt ein
+Totalschaden.

 ---

 ## Stack

-| Backend | Frontend (geplant) |
-|---------|---------------------|
-| Go 1.26 | React 19, TypeScript 5.9 |
-| net/http (Standard-Library-first) | Vite 8, Tailwind CSS |
-| SQLite (geplant) | enterprise.css Design-System (enconf-Pattern) |
+Bewusst langweilig, ein Binary, lokal lauffähig:
+
+| Bereich | Wahl |
+|---|---|
+| Sprache | Go 1.26, Standard-Library wo möglich |
+| Web | `net/http` + `html/template` + htmx, kein Frontend-Build, kein React |
+| Datenbank | PostgreSQL über `pgx`, Migrationen über `golang-migrate` |
+| PDF | serverseitig erzeugt |
+| Zeitstempel | RFC-3161 von einer öffentlichen TSA |
+| Extraktion | Claude API (nur Fakten-Extraktion, siehe oben) |
+| Design | `design/enterprise.css` (Enterprise Light Theme, enconf-Pattern, Primärfarbe `#1677ff`) |
+
+Kein Docker für die App selbst, kein React, keine Queue. Neue
+Abhängigkeiten nur nach Rückfrage.
+
+**Warum Postgres statt SQLite:** Das Produkt läuft von Anfang an für
+hunderte gleichzeitige Nutzer über mehrere Mandanten (Creator, Agentur,
+Marke, Kanzlei). Ein revisionssicheres Beweisarchiv braucht robuste
+Concurrent-Writes sowie Point-in-Time-Recovery/Replikation — das ist mit
+SQLites Single-Writer-Modell nicht sauber zu bauen. Gehostet wird
+Managed Postgres in der EU (DSGVO).

 **Pfad:** `/var/www/deklarix` | **Git:** `https://git.netcell-it.de/projekte/deklarix` | **Branch:** `main`

@@ -21,21 +91,27 @@
 ```
 /var/www/deklarix/
 ├── cmd/
-│   └── server/
-│       └── main.go            # Entry Point
+│   └── deklarix/
+│       └── main.go            # Entry Point, HTTP-Server
 ├── internal/
-│   ├── config/                # Konfiguration (env-basiert)
-│   ├── handler/               # HTTP Handler
-│   └── middleware/            # Auth, Logging, CORS
+│   ├── extract/                # Claude-API-Aufruf, JSON-Schema, Validierung
+│   ├── rules/                  # YAML-Loader, Auswertung, Versionierung
+│   ├── evidence/                # Hashing, Zeitstempel, Append-only-Log
+│   ├── dossier/                 # PDF-Erzeugung
+│   ├── store/                   # Postgres, Migrationen
+│   └── web/                     # Handler, Templates
+├── rules/                      # YAML-Regeln, versioniert im Git
+├── testdata/
+│   └── golden/                 # Golden-Tests: Beispielbeiträge + erwartetes Ergebnis
 ├── design/
-│   └── enterprise.css         # Gemeinsames Design-System (enconf-Basis)
+│   └── enterprise.css          # Design-System (enconf-Basis)
 ├── packaging/
 │   └── DEBIAN/
-│       └── control.tmpl       # .deb Package-Control-Template
+│       └── control.tmpl        # .deb Package-Control-Template
 ├── scripts/
-│   ├── build.sh               # Cross-Compile amd64 + arm64
-│   ├── test.sh                # Tests + vet + build-check
-│   └── release.sh             # Vollständiger Release-Prozess
+│   ├── build.sh                # Cross-Compile amd64 + arm64
+│   ├── test.sh                 # Tests + vet + build-check
+│   └── release.sh              # Vollständiger Release-Prozess
 ├── go.mod
 ├── go.sum
 └── CLAUDE.md
@@ -43,13 +119,39 @@

 ---

+## Datenmodell
+
+Fünf Tabellen, mehr braucht der MVP nicht:
+
+- `submission` — ein eingereichter Beitrag, Status, Zeitpunkte
+- `asset` — Bild oder Datei, Pfad, SHA-256
+- `extraction` — das JSON aus Stufe 1, Modellversion, Prompt-Version
+- `finding` — Ergebnis pro Regel: Regel-ID, Regel-Version, Schwere, Text
+- `evidence_package` — Dossier, Hash, Zeitstempel-Token, erzeugt am
+- `participant` — Beteiligter an einer Submission mit Rolle
+  (`creator`, `agentur`, `marke`, `kanzlei`) und Beitrag zur
+  Verantwortungsmatrix (wer hat vorgegeben, wer freigegeben)
+
+**Append-only.** Kein UPDATE auf `finding`, `extraction` oder
+`evidence_package`. Korrekturen sind neue Zeilen mit Verweis auf die alte.
+Ein Beweisarchiv, in dem man Zeilen ändern kann, ist kein Beweisarchiv.
+
+**Beweiskette:** SHA-256 über jedes Asset und über die kanonisierte
+JSON-Repräsentation der Metadaten, RFC-3161-Zeitstempel über diesen Hash.
+Dossier-PDF enthält Beitrag, Caption, Kennzeichnung, Findings mit
+Fundstellen, Vertrags- und Briefing-Bezug, Verantwortungsmatrix, alle
+Hashes und das Zeitstempel-Token. Vollständiger Export muss für den
+Nutzer jederzeit möglich sein — wer kündigt, bekommt sein Archiv.
+
+---
+
 ## Go Commands

 ```bash
 export PATH=$PATH:/usr/local/go/bin   # Immer setzen!

 # Entwickeln
-go run ./cmd/server/
+go run ./cmd/deklarix/

 # Tests
 ./scripts/test.sh
@@ -95,11 +197,11 @@ git add -p && git commit -m "feat: ..."

 ---

-## Testing-Pattern
+## Testing-Pattern & Qualitätssicherung

 ```go
-// Datei: internal/handler/health_test.go
-package handler_test
+// Datei: internal/web/health_test.go
+package web_test

 import (
    "net/http"
@@ -117,30 +219,57 @@ func TestHealth(t *testing.T) {
 }
 ```

- Tests liegen neben dem Code: `handler/foo_test.go`
+- Tests liegen neben dem Code: `paket/foo_test.go`
 - Package: `package foo_test` (Black-Box-Test) oder `package foo` (White-Box)
 - Race-Detector immer an: `go test -race ./...`
 - Tabellenbasierte Tests für mehrere Inputs

+**DATABASE_URL und Testsystem.** `internal/store` hat Integrationstests
+gegen echtes Postgres (u. a. die Append-only-Garantie). Ohne
+`DATABASE_URL` überspringt `go test` diese Tests einfach — praktisch für
+schnelle lokale Iteration ohne lokales Postgres. `./scripts/test.sh`
+(und damit `release.sh`) ist strenger: es bricht ohne `DATABASE_URL` mit
+Fehler ab, statt die Append-only-Garantie still zu überspringen. Es
+zieht dafür aber **kein** eigenes Postgres hoch (kein Docker-Zwang auf
+dem lokalen Dev-Rechner) — das ist Aufgabe des dedizierten Testsystems,
+dort muss `DATABASE_URL` vorkonfiguriert sein.
+
+**Golden-Test-Suite ist das eigentliche Asset des Projekts, nicht die
+UI.** 30 bis 50 Beispielbeiträge in `testdata/golden/`, abgeleitet aus
+veröffentlichten Urteilen und Beanstandungen der Medienanstalten, jeweils
+mit erwarteten Findings. Jede Regeländerung läuft gegen die komplette
+Suite. Eine Regeländerung, die ein Golden-Ergebnis kippt, wird nicht
+gemerged, ohne dass der erwartete Wert bewusst und dokumentiert angepasst
+wird. Extraktion wird separat getestet: fixierte Eingaben, geprüfte
+JSON-Ausgabe.
+
 ---

-## Design-System
+## Leitplanken, die dauerhaft gelten

-Das Frontend folgt dem **Enterprise Light Theme** aus enconf (`design/enterprise.css`).
-
- **Primärfarbe:** `#1677ff` (Blau)
- **Sidebar:** Dunkel (`#0B1426` → `#101D33`) mit weißen Icons
- **Body:** `#F8FAFC` Hintergrund, `#334155` Text
- **Font:** Inter (von `/fonts/inter.css` oder Google Fonts)
- **Radius:** 6px / 8px / 10px
-
-Für neue Frontend-Projekte unter `/var/www/deklarix`:
-```bash
-# Frontend-Scaffold (wenn benötigt)
-npm create vite@latest frontend -- --template react-ts
-cd frontend && npm install
-# enterprise.css aus design/ einbinden
-```
+- **Keine Rechtsdienstleistung.** Deklarix ist ein Werkzeug, keine
+  Rechtsberatung. Keine Formulierung darf eine individuelle rechtliche
+  Bewertung suggerieren. Auf jedem Screen mit einem Ergebnis steht ein
+  entsprechender Hinweis. Keine Erfolgsaussichten-Aussagen.
+- **Keine Versicherungssprache.** Nie „Abmahnschutz“, „abgesichert“,
+  „geschützt“, „Kostenübernahme“ — sonst erlaubnispflichtiges
+  Versicherungsgeschäft. Immer „Prüfung“, „Hinweis“, „Dokumentation“,
+  „Nachweis“.
+- **Keine erfundenen Fundstellen.** Jede Norm und jedes Urteil steht in
+  einer Regel-YAML und wurde dort von Hand geprüft.
+- **Nur eigene Inhalte.** Kein Scraping fremder Accounts, keine fremden
+  Posts als Demo-Material. Demo-Material ist synthetisch. Nutzerinhalte
+  kommen über eigenen OAuth-Zugang oder Datenexport.
+- **DSGVO und Hosting in der EU.** Löschkonzept von Anfang an mitdenken,
+  aber Beweisarchiv und Löschpflicht sauber gegeneinander abgrenzen
+  (offener Punkt, siehe unten).
+- **Berufsrecht der Anwälte (§ 49b Abs. 3 S. 1 BRAO).** Kein Routing
+  (kein Button, der einen Fall an eine Kanzlei übergibt — Nutzer wählt
+  selbst aus dem Verzeichnis), kein ergebnisabhängiger Preis, keine
+  Sachvorteile an gelistete Kanzleien, Verzeichnis bleibt kostenlos
+  (BGH IX ZR 89/23: entgeltliche Mandatsvermittlung ist nichtig). Vor dem
+  ersten Kanzlei-Vertrag: formlose Auskunft der zuständigen
+  Rechtsanwaltskammer einholen.

 ---

@@ -170,7 +299,7 @@ git push origin main
 ### Server-Prozess
 ```bash
 # Start (manuell)
-PORT=8080 ./dist/deklarix_latest_amd64 &
+PORT=8080 DATABASE_URL=postgres://... ANTHROPIC_API_KEY=... ./dist/deklarix_latest_amd64 &

 # Logs prüfen
 journalctl -u deklarix -f
@@ -178,6 +307,20 @@ journalctl -u deklarix -f

 ---

+## Arbeitsweise für Claude Code
+
+- Kleine Commits, ein Thema pro Commit
+- Erst Test oder Golden-Fall, dann Implementierung
+- Keine neue Abhängigkeit ohne Rückfrage
+- Keine Umbenennung von Regel-IDs; Regeln werden versioniert, nicht
+  ersetzt
+- Fehler nicht verschlucken, keine stillen Fallbacks bei der Extraktion
+- Bei Unsicherheit über eine Rechtsfrage: nicht raten, sondern als offene
+  Frage in `rules/OPEN.md` notieren
+- Der Code-RAG dient der Orientierung im Bestand, nicht als Nachweis von
+  Korrektheit. Verifiziert wird durch Compiler, Tests und die
+  Golden-Suite.
+
 ## Vor Änderungen

 1. `go vet ./...` — keine Fehler
@@ -190,3 +333,12 @@ journalctl -u deklarix -f
 2. `./scripts/build.sh <version>` → erfolgreich
 3. Commit mit semantischer Message: `feat:`, `fix:`, `refactor:`, `docs:`
 4. Bei Release: `./scripts/release.sh <version>`
+
+---
+
+## Offene Punkte
+
+- Umfang des Regelsatzes für den ersten Pilotkunden festlegen
+- Welche TSA für die Zeitstempel
+- Löschkonzept versus Beweisarchiv sauber ausformulieren
+- Markenanmeldung Deklarix, sobald erster Kunde zahlt