# go-documenter — Architekturdokumentation (arc42)

> Detaildokument zur Architektur. Das [README](../README.md) bleibt der fachliche Überblick;
> dieses Dokument konkretisiert Bausteine, Abläufe, Technologien und Entscheidungen (DEC-*).
> Anforderungen als testbare Gherkin-Szenarien: [doc/requirements/](requirements/).
> API-Vertrag: [doc/openapi.yaml](openapi.yaml).

## 1. Einführung und Ziele

Schlankes, serverseitiges Dokumentenmanagement-System (Single-User) in Go:

- Import von **PDF- und Bilddateien** (JPG, PNG, HEIC) über API oder überwachten Ordner
- Verarbeitung: Textextraktion, OCR, optionale LLM-Anreicherung, Volltextindexierung
- Finale Ablage in Jahresordnern; **Originaldateien werden niemals inhaltlich verändert**
- Nachvollziehbarkeit aller Zustandsänderungen durch Event Sourcing
- API-first: kein Frontend in der ersten Ausbaustufe

Qualitätsziele (Rangfolge): Einfachheit, Testbarkeit, Nachvollziehbarkeit, Zuverlässigkeit, Erweiterbarkeit.

## 2. Randbedingungen

| Randbedingung | Ausprägung |
|---|---|
| Sprache | Go (~1.26) |
| Betrieb | Eigener VServer (Strato, 8 GB RAM) hinter Caddy-Reverse-Proxy, Docker Compose |
| CI/CD | Gitea + Actions (git2.adelante-it.de, `go-ci`-Runner-Image, gespiegelte Actions) |
| Vorgehen | **Dokumentation vor Implementierung** (dieses Dokument ist das Gate), TDD über Gherkin-Szenarien |
| Dokumentation | arc42, deutsch; Diagramme in Mermaid (DEC-DOC-01) |
| Referenzprojekte | pamietnik (Go-Konventionen), infranas (Betriebsumgebung) |

## 3. Kontextabgrenzung

```mermaid
flowchart LR
    client["API-Client<br/>(curl, Skripte, späteres Frontend)"]
    user["Nutzer<br/>(legt Dateien ab)"]
    llm["LLM-Dienst<br/>OpenAI-kompatibel<br/>(LocalAI via VPN oder Cloud)"]

    subgraph host["Server (Docker)"]
        sys["go-documenter"]
        import["import/ (überwacht)"]
        archive["archive/{Jahr}/"]
        data["data/ (SQLite, Staging, Logs)"]
    end

    client -- "HTTPS + Bearer-Token" --> sys
    user -- "Datei speichern" --> import
    sys -- "liest / verschiebt" --> import
    sys -- "legt ab (unverändert)" --> archive
    sys -- "Events, Projektion, FTS-Index" --> data
    sys -- "Chat-Completions (optional)" --> llm
```

Externe Schnittstellen:

- **API-Clients**: REST/JSON, Bearer-Token (`API_TOKEN`), Vertrag in `doc/openapi.yaml`
- **Dateisystem**: `import/` (Eingang), `data/staging/` (Verarbeitung), `archive/` (Ablage)
- **LLM**: OpenAI-kompatible Chat-Completions-API; erreichbar oder nicht — das System funktioniert ohne
- **OCR**: keine externe Schnittstelle — `ocrmypdf`/`tesseract` sind im Container gebündelt

## 4. Lösungsstrategie

| Bereich | Wahl | Begründung |
|---|---|---|
| HTTP | `github.com/go-chi/chi/v5` | minimal, stdlib-kompatibel, pamietnik-Standard |
| Persistenz | `modernc.org/sqlite` (pure Go) | eine Datei, WAL, kein CGo, kein DB-Server |
| Volltextsuche | SQLite FTS5 (external content, BM25) | transaktional konsistent mit den Daten, kein Zweitsystem |
| OCR | `ocrmypdf --sidecar --output-type none` (PDF), `tesseract` (Bilder) | nur Text wird gewonnen, Original bleibt byte-identisch |
| PDF-Text | `pdftotext` (poppler) via `exec.Command` | beste Extraktionsqualität, Interface-gekapselt |
| LLM | eigener Minimal-Client (Stdlib-HTTP) | LocalAI ↔ Cloud nur per Config umschaltbar, kein SDK |
| Event Sourcing | handgerollt, nur Dokument-Aggregat | erfüllt Nachvollziehbarkeit ohne Framework-Komplexität |
| Watcher | `fsnotify` + periodischer Rescan | Rescan fängt verpasste Events und Startbestand |
| Config | YAML + Env-Override (Secrets nur Env) | pamietnik-Muster |
| Logging | `log/slog` JSON + lumberjack-Rotation | strukturiert, pamietnik-Muster |
| Tests | nur Stdlib `testing`, handgeschriebene Fakes | keine Mock-Frameworks, Interfaces als Test-Seams |

Vollständige Dependency-Liste: `chi/v5`, `modernc.org/sqlite`, `fsnotify`, `google/uuid`, `yaml.v3`, `lumberjack.v2`. Sonst nichts.

## 5. Bausteinsicht

### 5.1 Überblick

```mermaid
flowchart TB
    subgraph api_layer["API-Schicht"]
        api["internal/api<br/>Router, Handler, Auth-Middleware"]
    end

    subgraph app["Anwendungslogik"]
        ingest["internal/ingest<br/>Aufnahme: UUID, Hash, Dedup, Staging"]
        pipeline["internal/pipeline<br/>Runner, Queue, Stages"]
        importer["internal/importer<br/>fsnotify + Rescan + Stabilität"]
    end

    subgraph domain_layer["Domäne"]
        domain["internal/domain<br/>Document, Status, MediaType"]
        events["internal/events<br/>Event-Store, Replay, Projektion"]
    end

    subgraph infra["Infrastruktur"]
        db["internal/db<br/>SQLite, Schema, Stores"]
        search["internal/search<br/>FTS5-Indexer/Searcher"]
        storage["internal/storage<br/>Datei-Moves, Jahresordner, Hash"]
        pdf["internal/pdf<br/>pdftotext"]
        ocr["internal/ocr<br/>ocrmypdf / tesseract"]
        llm["internal/llm<br/>OpenAI-kompatibler Client"]
        config["internal/config"]
    end

    api --> ingest
    api --> db
    api --> search
    api --> events
    importer --> ingest
    ingest --> events
    ingest --> storage
    ingest --> pipeline
    pipeline --> events
    pipeline --> pdf
    pipeline --> ocr
    pipeline --> llm
    pipeline --> search
    pipeline --> storage
    events --> db
    search --> db
```

Abhängigkeitsregel: `domain` und `events` importieren keine Infrastruktur. Stages und Handler
hängen nur von schmalen Interfaces ab; die konkreten Implementierungen (exec, SQLite, HTTP)
werden in `cmd/server/main.go` verdrahtet.

### 5.2 Pakete

| Paket | Verantwortung |
|---|---|
| `cmd/server` | Wiring: Config → Logger → DB → Stores → Worker + Importer → HTTP-Server; graceful shutdown |
| `internal/domain` | Reine Typen: `Document`, Status-Konstanten, `MediaType` — keine Abhängigkeiten |
| `internal/events` | Event-Envelope + Payload-Structs, `Store`-Interface, SQLite-Store (Append + synchrone Projektion in einer Transaktion), `Replay` |
| `internal/pipeline` | `Stage`-Interface, kanonische Reihenfolge, Worker-Loop, DB-backed Work-Queue mit Lease |
| `internal/ingest` | Gemeinsame Aufnahme für API und Ordner: UUID, SHA-256, Dedup, Staging, `DocumentReceived`, Enqueue |
| `internal/pdf` | `TextExtractor`-Interface + pdftotext-Implementierung, `needs_ocr`-Heuristik |
| `internal/ocr` | `Processor`-Interface; ocrmypdf-Sidecar (PDF), tesseract (Bilder), HEIC→temp-PNG |
| `internal/llm` | `Client`-Interface, OpenAI-kompatible Implementierung, `Enricher` (Prompt + JSON-Parsing) |
| `internal/search` | `Indexer`/`Searcher`-Interfaces, FTS5-Implementierung inkl. Rebuild |
| `internal/importer` | Ordnerüberwachung: fsnotify, Stabilitäts-Detektor, periodischer Rescan |
| `internal/storage` | Datei-Lebenszyklus: Staging-Pfade, Jahresordner, Umbenennung, Hash, atomare Moves — **nie Inhaltsänderung** |
| `internal/api` | `NewRouter(RouterDeps)`, Handler je Ressource, Bearer-Token-Middleware, `writeError`/`writeJSON` |
| `internal/db` | `Open` (WAL, busy_timeout, foreign_keys), idempotentes Schema (go:embed), Store-Interfaces + Sentinel-Errors |
| `internal/config` | YAML + Env-Override; Secrets ausschließlich per Env |

### 5.3 Zentrale Typen (Klassendiagramm)

```mermaid
classDiagram
    class Document {
        +string ID  «UUIDv4»
        +Status Status
        +string OriginalName
        +MediaType MediaType
        +string Origin  «api | import_folder»
        +string ContentHash  «SHA-256»
        +int64 SizeBytes
        +int PageCount
        +string StoragePath
        +string ArchivePath
        +string Text
        +bool NeedsOCR
        +string Title
        +string Summary
        +List~string~ Tags
        +string DocDate
        +string Language
        +bool Enriched
        +string FailedStage
        +string LastError
        +int Attempts
        +int Version  «Seq des letzten Events»
    }

    class Event {
        +string AggregateID
        +int Seq
        +string Type
        +json.RawMessage Payload
        +time.Time CreatedAt
    }

    class Store {
        <<interface>>
        +Append(ctx, aggregateID, expectedVersion, payloads) error
        +Load(ctx, aggregateID) List~Event~
    }

    class Stage {
        <<interface>>
        +Name() string
        +Skip(doc Document) bool
        +Run(ctx, doc Document) List~Payload~
    }

    class Queue {
        <<interface>>
        +Enqueue(ctx, documentID, stage) error
        +Claim(ctx, workerID) *Work
        +Complete(ctx, documentID) error
        +Defer(ctx, documentID, notBefore) error
    }

    class TextExtractor {
        <<interface>>
        +Extract(ctx, path) ExtractResult
    }
    class OCRProcessor {
        <<interface>>
        +Recognize(ctx, path, mediaType) OCRResult
    }
    class Enricher {
        <<interface>>
        +Enrich(ctx, text) Enrichment
    }
    class Indexer {
        <<interface>>
        +Index(ctx, doc Document) error
        +Rebuild(ctx) error
    }
    class Filer {
        <<interface>>
        +File(ctx, doc Document) string  «archive_path»
    }

    Store ..> Event
    Store ..> Document : Replay(events) → Document
    Stage ..> Document
    Stage <|.. ExtractStage
    Stage <|.. OCRStage
    Stage <|.. EnrichStage
    Stage <|.. IndexStage
    Stage <|.. FileStage
    ExtractStage --> TextExtractor
    OCRStage --> OCRProcessor
    EnrichStage --> Enricher
    IndexStage --> Indexer
    FileStage --> Filer
```

### 5.4 Event-Modell

| Event | Payload (snake_case) | Wirkung im Replay |
|---|---|---|
| `DocumentReceived` | original_name, media_type, origin, content_hash, size_bytes, staging_path, imported_at | Aggregat entsteht, Status `received` |
| `ProcessingStarted` | attempt | Status `processing` |
| `TextExtracted` | text, page_count, char_count, method, needs_ocr | Text/Seiten gesetzt |
| `OCRCompleted` | text, engine, languages, duration_ms | Text gesetzt, Status `ocr_done` |
| `DocumentEnriched` | title, summary, tags[], doc_date, language, model, prompt_version | Metadaten gesetzt, Status `enriched` |
| `EnrichmentSkipped` | reason, attempts | enriched=false, Pipeline läuft weiter |
| `DocumentIndexed` | char_count, indexed_at | Status `indexed` |
| `DocumentFiled` | archive_path, filed_at, timestamp_applied | Status `filed` (Endzustand) |
| `ProcessingFailed` | stage, attempt, error, retryable | Status `failed`, FailedStage/LastError gesetzt |
| `RetryRequested` | requested_by, from_stage | Status `processing`, Wiederaufnahme |

`Replay(events) → Document` ist eine pure Fold-Funktion — der Zustand ist vollständig aus
Events rekonstruierbar. Der **Volltext liegt im Event-Payload** (DEC-ES-02), damit auch die
Projektion und der Suchindex jederzeit aus dem Event-Store neu aufgebaut werden können.

### 5.5 Statusmodell

```mermaid
stateDiagram-v2
    [*] --> received : DocumentReceived
    received --> processing : ProcessingStarted
    processing --> ocr_done : OCRCompleted
    processing --> enriched : DocumentEnriched
    ocr_done --> enriched : DocumentEnriched
    processing --> indexed : DocumentIndexed  (Enrich übersprungen)
    ocr_done --> indexed : DocumentIndexed  (Enrich übersprungen)
    enriched --> indexed : DocumentIndexed
    indexed --> filed : DocumentFiled
    processing --> failed : ProcessingFailed
    ocr_done --> failed : ProcessingFailed
    enriched --> failed : ProcessingFailed
    indexed --> failed : ProcessingFailed
    failed --> processing : RetryRequested
    filed --> [*]
```

## 6. Laufzeitsicht

### 6.1 Import über überwachten Ordner

```mermaid
sequenceDiagram
    actor N as Nutzer
    participant W as importer (Watcher)
    participant I as ingest
    participant S as storage
    participant E as events (Store)
    participant Q as work_queue

    N->>W: Datei in import/ speichern
    W->>W: fsnotify-Event → Datei "pending"
    loop bis Größe+mtime stable_seconds unverändert
        W->>W: Stabilität prüfen
    end
    W->>I: Ingest(pfad, origin=import_folder)
    I->>S: SHA-256 berechnen (streaming)
    I->>E: Dedup-Check (content_hash)
    alt Duplikat
        I->>S: Datei nach import/rejected/ verschieben
        I-->>W: Warnung geloggt, kein Aggregat
    else neu
        I->>I: UUID vergeben
        I->>S: Move nach data/staging/{uuid}.{ext}
        I->>E: Append(DocumentReceived)
        Note over E: Event + documents-Projektion<br/>in EINER Transaktion
        I->>Q: Enqueue(uuid, next_stage=extract)
    end
```

### 6.2 Verarbeitung durch die Pipeline (Worker)

```mermaid
sequenceDiagram
    participant Q as work_queue
    participant R as pipeline (Runner)
    participant E as events (Store)
    participant X as ExtractStage (pdftotext)
    participant O as OCRStage (ocrmypdf/tesseract)
    participant L as EnrichStage (LLM)
    participant F as IndexStage / FileStage

    loop Poll alle 2 s
        R->>Q: Claim (Lease 15 min)
    end
    Q-->>R: document_id, next_stage
    R->>E: Load + Replay → Document
    alt Stage = extract (nur lesend!)
        R->>X: Run(doc)
        X-->>R: TextExtracted{needs_ocr}
    else Stage = ocr (Original bleibt byte-identisch)
        R->>O: Run(doc)
        Note over O: PDF: ocrmypdf --sidecar --output-type none<br/>Bild: tesseract direkt (HEIC → temp-PNG)
        O-->>R: OCRCompleted{text}
    else Stage = enrich (optional)
        R->>L: Run(doc)
        alt LLM erreichbar
            L-->>R: DocumentEnriched{title, tags, …}
        else LLM offline
            L-->>R: Fehler (retryable)
            R->>E: Append(ProcessingFailed{retryable})
            R->>Q: Defer(not_before = now + Backoff)
            Note over R,Q: nach max. Versuchen:<br/>EnrichmentSkipped → weiter zu index
        end
    else Stage = index / file
        R->>F: Run(doc)
        F-->>R: DocumentIndexed / DocumentFiled{archive_path}
    end
    R->>E: Append(Events, expectedVersion)
    R->>Q: next_stage weiterschalten bzw. Complete bei filed
```

### 6.3 Import über API

```mermaid
sequenceDiagram
    actor C as API-Client
    participant A as api (Handler)
    participant I as ingest
    participant Q as work_queue

    C->>A: POST /v1/documents (multipart, Bearer-Token)
    A->>A: Auth-Middleware (constant-time Vergleich)
    A->>I: Ingest(stream, origin=api)
    Note over I: Stream → staging/{uuid}.{ext}.part<br/>TeeReader → SHA-256, dann Rename
    alt Duplikat
        I-->>A: ErrDuplicate + existing_id
        A-->>C: 409 {error, existing_document_id}
    else neu
        I->>Q: DocumentReceived + Enqueue
        A-->>C: 202 {id, status: received}
    end
    Note over C: weiterer Ablauf identisch zu 6.2
```

### 6.4 Suche

```mermaid
sequenceDiagram
    actor C as API-Client
    participant A as api
    participant S as search (FTS5)

    C->>A: GET /v1/search?q=rechnung+stadtwerke
    A->>S: Search(q, limit, offset)
    S->>S: MATCH + bm25() + snippet()
    S-->>A: [{id, title, snippet, rank}, …]
    A-->>C: 200 {results, total}
```

### 6.5 Fehlerfall und Wiederaufnahme (Retry/Resume)

```mermaid
sequenceDiagram
    actor C as API-Client
    participant A as api
    participant E as events
    participant Q as work_queue
    participant R as Runner

    Note over E: Dokument steht auf failed<br/>(ProcessingFailed{stage=ocr, retryable=false})
    C->>A: POST /v1/documents/{id}/reprocess
    A->>Q: geclaimt? → 409, sonst weiter
    A->>E: Append(RetryRequested{from_stage})
    A->>Q: Enqueue(id)
    A-->>C: 202
    R->>E: Load + Replay
    Note over R: Resume-Stage ableitbar aus Zustand:<br/>erste Stage der kanonischen Reihenfolge,<br/>deren Ergebnis fehlt — fertige Stages laufen nie erneut
    R->>R: Pipeline ab OCR fortsetzen
```

## 7. Verteilungssicht

```mermaid
flowchart TB
    subgraph vserver["Strato VServer (Ubuntu 24.04)"]
        caddy["Caddy<br/>:80/:443, TLS/ACME"]
        subgraph compose["/opt/documenter (Docker Compose)"]
            app["documenter-api-1<br/>:9060 intern<br/>debian-slim + ocrmypdf/tesseract/poppler/libheif"]
            vol1[("config/")]
            vol2[("data/ — SQLite, Staging, Logs")]
            vol3[("import/")]
            vol4[("archive/")]
        end
        caddy -- "proxy-Netzwerk<br/>(Host-Header-Routing)" --> app
        app --- vol1 & vol2 & vol3 & vol4
    end
    subgraph xps["XPS15 (NetBird-VPN, ggf. offline)"]
        localai["LocalAI :8080<br/>OpenAI-kompatibel"]
    end
    subgraph git2["git2.adelante-it.de"]
        gitea["Gitea: Repo + Registry + Actions<br/>act_runner (go-ci)"]
    end
    app -. "Chat-Completions<br/>(optional)" .-> localai
    gitea -- "Release: Image push,<br/>Deploy: compose pull && up -d" --> compose
```

- Keine veröffentlichten Container-Ports; Caddy erreicht den Container über das externe `proxy`-Netzwerk
- Secrets (`API_TOKEN`, `LLM_API_KEY`) via `/opt/documenter/.env`, nie im Repo
- Dockerfile: Builder `golang:1.26-alpine` (CGO_ENABLED=0) → Runtime `debian:trixie-slim` mit `ocrmypdf tesseract-ocr-deu tesseract-ocr-eng poppler-utils libheif-examples`, non-root (DEC-RUNTIME-01)
- Offener Punkt: Erreichbarkeit von LocalAI (VPN-Adresse) aus dem Container früh verifizieren

## 8. Querschnittliche Konzepte

### 8.1 Speicherkonzept (DEC-STORAGE-01)

Genau **zwei Speicherorte**, keine weiteren Systeme:

1. **Eine SQLite-Datei** (`data/documenter.db`): Event-Store (Quelle der Wahrheit),
   `documents`-Projektion (Read Model), FTS5-Index, Work-Queue. Eine Datei = eine
   Backup-Einheit; transaktionale Konsistenz gratis; WAL für parallele API-/Worker-Zugriffe.
2. **Plain-Dateisystem**: `import/` (+ `rejected/`), `data/staging/`, `archive/{JJJJ}/`.
   Keine Blobs in der DB — Dateien bleiben normale, menschenlesbare Dateien.

Robustheit:

- Originale byte-identisch; nur `os.Rename` (cross-device: copy+fsync+rename), `.part`-Suffix
  während Schreibvorgängen — nie halbe Dateien sichtbar
- Verknüpfung Datei↔Kontext doppelt: **UUID im Dateinamen** (Datei→DB) + **SHA-256 in der DB** (DB→Datei)
- Gestaffelte Wiederherstellung: FTS kaputt → Rebuild-API; Projektion kaputt → Replay aus Events;
  DB weg → Dateien bleiben lesbar und über die UUID identifizierbar
- Backup: genau zwei Verzeichnisse (`data/` + `archive/`) per rsync/Snapshot

### 8.2 Unveränderlichkeit der Originale (DEC-IMMUTABLE-01)

Dateien werden ab Aufnahme nur gelesen, verschoben und umbenannt — nie inhaltlich verändert.
OCR erzeugt ausschließlich Sidecar-Text (`ocrmypdf --output-type none` bzw. tesseract-Ausgabe);
es wird kein Textlayer eingebettet, keine Bild→PDF-Konvertierung für die Ablage vorgenommen.
Kontext (Text, Tags, Titel, Events) lebt vollständig extern in der DB.
Verifikation: SHA-256 vor Import == SHA-256 der archivierten Datei (fester Testfall).

### 8.3 Datei-Lebenszyklus und Benennung (DEC-NAME-01, DEC-YEAR-01, DEC-DUP-01)

- Ablagepfad: `archive/{JJJJ}/{JJJJMMTT-HHMMSS_}bereinigter-name_{uuid}.{ext}`
- Jahr = **Importzeitpunkt** (deterministisch, LLM-unabhängig); Zeitstempel-Präfix per Config
- Dedup per SHA-256 (UNIQUE-Index): API → `409` + `existing_document_id`; Watcher → `import/rejected/`
- Grenze: erneuter Scan desselben Papierdokuments erzeugt andere Bytes und wird nicht erkannt

### 8.4 Ereignisorientierung und Konsistenz (DEC-ES-01, DEC-ES-02)

Event Sourcing nur für das Dokument-Aggregat, handgerollt (~200 Zeilen):
append-only `events`-Tabelle, `PRIMARY KEY(aggregate_id, seq)` als optimistische
Nebenläufigkeitskontrolle, **synchrone Projektion** in derselben Transaktion — das Read
Model ist nie stale. Retries und Übersprünge sind selbst Events (`RetryRequested`,
`EnrichmentSkipped`), die Wiederaufnahme-Stage ist rein aus dem Replay-Zustand ableitbar.

### 8.5 Fehlerbehandlung und Wiederanlauf (DEC-QUEUE-01)

- DB-backed Work-Queue mit Lease (15 min): Neustart- und Crash-sicher, verwaiste Claims
  werden übernommen; 1 Worker (konfigurierbar), Poll-Intervall 2 s
- Retryable Fehler (LLM offline, OCR-Timeout): exponentieller Backoff 30s·2ⁿ (Cap 1 h),
  max. Versuche konfigurierbar (Default 10)
- Enrichment ist **optional**: nach erschöpften Versuchen `EnrichmentSkipped` und die
  Pipeline läuft weiter — ein offlines LLM blockiert nie die Ablage
- Nicht-retryable Fehler (korrupte Datei, passwortgeschütztes PDF): Status `failed`,
  manuell per `POST /v1/documents/{id}/reprocess` wiederaufnehmbar

### 8.6 Logging

- `log/slog`, JSON-Handler; stdout + optional Datei mit lumberjack-Rotation
  (`max_size_mb`/`max_backups`/`max_age_days`); Level per Config/Env
- HTTP-Zugriffe über chi-Middleware; jede Pipeline-Stage loggt strukturiert:
  `slog.Info("stage done", "document_id", id, "stage", name, "duration_ms", ms)`
- Fehler immer mit `"err"`, `"stage"`, `"attempt"` — Korrelation über `document_id`

### 8.7 Testbarkeit und TDD (DEC-REQ-01)

- Anforderungen als **Gherkin-Szenarien** in [doc/requirements/](requirements/), je Szenario
  ein gleichnamiger Stdlib-Test; Traceability-Tabelle je Datei. Workflow: Szenario → roter Test → Implementierung
- Nur Stdlib `testing`, table-driven, handgeschriebene In-Memory-Fakes; Interfaces als Seams
- exec-basierte Komponenten (ocrmypdf, pdftotext, tesseract) über injizierbaren
  `runner func(ctx, name, args...)`-Seam testbar; LLM über `httptest.Server`
- Echte SQLite (in-memory/tmpfile) inkl. FTS5 in DB- und Integrationstests
- Zwei Integrationstests im normalen `go test ./...`: API-Upload → `filed` + suchbar;
  Ordner-Import → gleiches Ergebnis

### 8.8 Sicherheit (DEC-AUTH-01)

- Statischer Bearer-Token (`API_TOKEN`, nur Env), Vergleich mit `crypto/subtle.ConstantTimeCompare`
- `/healthz` öffentlich, alles andere tokenpflichtig; TLS terminiert Caddy
- Upload-Limit per Config (Default 100 MB); nur Whitelist-Endungen (`pdf|jpg|jpeg|png|heic`)

## 9. Architekturentscheidungen (DEC-*)

| ID | Entscheidung | Begründung / Trade-off |
|---|---|---|
| DEC-STACK-01 | Go + chi + SQLite + slog, pamietnik-Konventionen | bewährt, minimal, ein Binary; bewusst kein Framework |
| DEC-DB-01 | `modernc.org/sqlite`, kein DB-Server | pure Go, eine Datei; Grenze: eine Schreib-Verbindung (für Single-User irrelevant) |
| DEC-FTS-01 | SQLite FTS5 external-content, Sync explizit in Go, Rebuild per API | kein Zweitsystem; offen: `trigram`-Tokenizer, falls Recall bei deutschen Komposita schlecht |
| DEC-ES-01 | Event Sourcing nur fürs Dokument-Aggregat, synchrone Projektion | volle Nachvollziehbarkeit ohne ES-Framework; keine Eventual-Consistency-Probleme |
| DEC-ES-02 | Volltext im Event-Payload | vollständige Rekonstruierbarkeit; DB-Wachstum durch Upload-Limit + Text-Cap begrenzt |
| DEC-QUEUE-01 | DB-backed Work-Claim-Queue mit Lease statt Go-Channels | Neustart-/Crash-sicher, kein Verlust; Trade-off: Poll-Latenz ≤ 2 s (akzeptiert) |
| DEC-IMMUTABLE-01 | **Originale nie verändern**; OCR nur als Sidecar-Text; Kontext extern | Hashes/Signaturen bleiben gültig, keine Render-Regressionen; Trade-off: archivierte PDFs haben keinen eingebetteten Textlayer — Suche läuft immer über das System |
| DEC-MEDIA-01 | PDF und Bilder (JPG/PNG/HEIC) in identischer Pipeline | ein Ablauf, eine Ablage; HEIC nur temporär für OCR konvertiert |
| DEC-NAME-01 | UUID im Archiv-Dateinamen + SHA-256 in DB | bidirektionaler, DB-unabhängiger Link; Trade-off: längere Dateinamen |
| DEC-YEAR-01 | Jahresordner aus Importdatum, nicht LLM-`doc_date` | deterministisch, funktioniert ohne LLM |
| DEC-DUP-01 | Dedup via SHA-256, Duplikate abgelehnt | einfach, exakt; erkennt keine Re-Scans desselben Papiers |
| DEC-OCR-01 | ocrmypdf (PDF) / tesseract (Bilder) via exec hinter Interface | beste Qualität, ein Container; Trade-off: ~600-MB-Image |
| DEC-EXTRACT-01 | `pdftotext` (poppler) via exec statt pure-Go-Lib | bessere Extraktion; Fat-Image ohnehin nötig |
| DEC-LLM-01 | OpenAI-kompatibler Minimal-Client; Anreicherung optional/retryable/nachholbar | LocalAI ↔ Cloud per Config; offlines LLM blockiert nie |
| DEC-RUNTIME-01 | Runtime-Image debian-slim statt distroless (Abweichung von pamietnik) | ocrmypdf/tesseract/poppler/libheif erforderlich |
| DEC-AUTH-01 | Statischer Bearer-Token, Single-User | ausreichend für v1; Revision bei Frontend/Multi-User |
| DEC-STORAGE-01 | Nur SQLite + Plain-Dateisystem | s. Kap. 8.1 |
| DEC-DOC-01 | Mermaid für alle Diagramme | nativ in Gitea gerendert, diffbar; Trade-off: kein Voll-UML (akzeptiert) |
| DEC-REQ-01 | Gherkin als Doku-Format + Stdlib-Tests (kein godog) | TDD-tauglich ohne Framework; Drift-Kontrolle über Namenskonvention + Traceability-Tabellen |

## 10. Qualitätsanforderungen

| Qualitätsziel | Konkretisierung / Prüfung |
|---|---|
| Einfachheit | 6 Dependencies, ein Binary, ein Container, eine DB-Datei |
| Testbarkeit | jedes Gherkin-Szenario hat einen benannten Test; `go test ./...` ohne externe Dienste |
| Nachvollziehbarkeit | `GET /v1/documents/{id}/events` zeigt lückenlosen fachlichen Verlauf |
| Konsistenz | Events + Projektion + FTS in einer Transaktion; Replay == Projektion (Testfall) |
| Zuverlässigkeit | Crash-Recovery über Queue-Lease; Stabilitäts-Detektor gegen halbe Dateien |
| Unversehrtheit | SHA-256 vor Import == SHA-256 im Archiv (Testfall) |
| Suchbarkeit | jedes verarbeitete Dokument per Inhalt findbar; Rebuild jederzeit möglich |
| Erweiterbarkeit | Frontend später gegen `doc/openapi.yaml`; neue Stages als weitere `Stage`-Implementierung |

## 11. Risiken und offene Punkte

| Risiko / offener Punkt | Einordnung / Maßnahme |
|---|---|
| OCR-Qualität schwankt | Original bleibt erhalten → jederzeit Re-OCR per `reprocess` möglich |
| LocalAI-Erreichbarkeit aus dem Container (VPN) | früh in M8 verifizieren; ggf. `extra_hosts`/Host-Forwarding |
| FTS5-Recall bei deutschen Komposita | beobachten; ggf. `trigram`-Tokenizer (DEC-FTS-01 offen) |
| Passwortgeschützte/korrupte PDFs | non-retryable `failed`; Szenario definiert |
| RAM bei parallelem OCR (VServer 8 GB) | v1: 1 Worker; OCR-Parallelität erst bei Bedarf |
| Spec-Drift Gherkin ↔ Tests | Namenskonvention + Traceability-Tabelle; optional später Lint-Skript |
| Backup-Automatisierung | offen; Muster: rsync wie pamietnik (infranas) |
| Watcher-Unterordner | v1: nein (nur Top-Level von `import/`) |
| Domain/Caddyfile-Eintrag | vor M9 festlegen |

## 12. Glossar

| Begriff | Bedeutung |
|---|---|
| Aggregat | Das Dokument als Einheit der Event-Sourcing-Konsistenz (eine UUID = ein Event-Stream) |
| Projektion / Read Model | `documents`-Tabelle, abgeleitet aus Events, für Abfragen und Suche |
| Sidecar-Text | OCR-Ausgabe als reine Textdatei, ohne das Quelldokument zu verändern |
| Staging | `data/staging/` — Zwischenbereich während der Verarbeitung |
| Stage | Ein Pipeline-Schritt (extract, ocr, enrich, index, file) hinter dem `Stage`-Interface |
| Work-Queue | DB-Tabelle, aus der der Worker Arbeit per Lease claimt |
| Lease | Zeitlich begrenzter Claim; läuft er ab, übernimmt ein Worker die Arbeit erneut |
| FTS5 | SQLite-Volltextsuchmodul (BM25-Ranking, Snippets) |
| external content | FTS5-Modus, bei dem der Index auf die `documents`-Tabelle zeigt statt Text zu duplizieren |