# KB filar #2 — Dokumenty (Nextcloud + Paperless) — design

> Dokument-master filaru dokumentow. Stoi pod `kb-00-overview.md`.
> Cel: kazda sesja / Claude Code startuje z pelnym kontekstem decyzji.
> Status: ARCHITEKTURA ZAMKNIETA (2026-07-01), implementacja modulowa czeka.
> Moduly implementacyjne: `docs/kb/modules/0X-*.md` — puszczane CC jeden po drugim.

---

## Kontekst — miejsce w architekturze KB

Filar #2 z czterech (maile > **dokumenty** > zdjecia > transakcje). Reuzywa ~80%
wzorca maili (text RAG + archiwum + embeddingi na SOLARIA), dokłada OCR i wlasna
migracje Drive -> self-host. Wpina sie w te sama koperte (`id/source/ts/geo/raw_ref/
entities[]`) i ten sam spine (Postgres+pgvector na PIHA).

Dwa zrodla dokumentow (dwa adaptery ingest):
- **Nextcloud** — zamiennik Drive, dowolne pliki + sync (WebDAV)
- **Paperless-ngx** — skany/faktury/umowy z OCR (Paperless API)

---

## Decyzje ZAMKNIETE

### Tozsamosc / SSO = Forgejo-OIDC
Forgejo (biega na PIHA, always-on, zweryfikowane docker ps) jest IdP. Nextcloud/
Paperless/Immich wpinaja sie przez natywny OIDC — wzorzec jak Vikunja (jedyny
dzisiejszy konsument). Authentik/forward-auth = otwarta przyszla opcja dla infra
(panele/monitoring bez OIDC), POZA zakresem KB. Spec: `modules/01-sso-forgejo-oidc.md`.

### Ingress = LAN/Tailscale only, ZERO public
Dokumenty to dane wrazliwe (faktury/umowy/prywatne pliki) — zasada kb-00 #4 local-first.
Wpinaja sie w **npm na PIHA** (LAN ingress :80/:443), NIE w npm na VPS (public).
Dostep spoza domu = przez Tailscale mesh. Zero certow public dla tych serwisow.

### Archiwum = HYBRYDA (kopia vs referencja per zrodlo)
- **Nextcloud -> KOPIA** do archiwum KB (pliki w Nextcloud znikaja/zmieniaja sie;
  KB robi snapshot przy ingescie, wersjonowanie przez append koperty)
- **Paperless -> REFERENCJA** (jego storage = zrodlo prawdy; KB trzyma raw_ref + OCR-text)
- **WARUNEK BRZEGOWY**: backup Paperless storage OBOWIAZKOWY (bo referencja = KB zalezy
  od zywotnosci Paperlessa; bez backupu = pojedynczy punkt awarii)

### Host = SPLIT serwis/OCR (rozwiazuje kolizje moc-vs-always-on)
Zadny pojedynczy node nie jest jednoczesnie mocny I always-on:
- VPS: RAM wyczerpany (121Mi wolne) — OUT
- PIHA: always-on ale ciasno (3.1Gi available, swap juz 2G uzyty)
- SOLARIA: mocarz (62Gi RAM, GPU, 315G) ale dostepnosc sesyjna (nie 24/7)

Rozwiazanie — rozdziel warstwy wg wymogu dostepnosci:
- **Paperless-serwis** (UI+API+Postgres+Redis) na **PIHA** — always-on, lekki w spoczynku,
  dostepny 24/7 dla zapytan KB. Miesci sie w 3.1Gi available (ciasno).
- **OCR-worker** na **SOLARIA** — CPU/GPU-glodny OCR batch (70k zalacznikow), podpiety
  do kolejki Redis@PIHA. 62Gi RAM stoi odlogiem.
- **FALLBACK**: SOLARIA spi -> OCR-worker na PIHA domiela wolno, ALBO zadania czekaja
  w kolejce Redis az SOLARIA wstanie (dokumenty nie sa pilne w sekundach).

Uzasadnienie splitu: OCR jest batch/async (fallback trywialny — kolejka czeka).
Stateful-serwis (baza) NIE fallbackuje latwo (replikacja pg = kruche) -> stoi w jednym
miejscu (PIHA). Wzorzec: "serwis always-on + compute-worker on-demand z fallback".

### PREREKWIZYT: odchudzic PIHA
PIHA na styku RAM (swap 2G uzyty). Przed deployem Paperlessa — audyt 33 shadow-kontenerow
(inwentaryzacja 2026-06-30): kandydaci do usuniecia/przeniesienia (elasticsearch 1Gi?
diskover? duplikaty exporterow?). Laczy sie z backlogiem grupy C. Spec: `modules/00-piha-slim.md`.

---

## Mapa modulow (kolejnosc egzekucji)

| # | Modul | Plik | Zalezy od |
|---|---|---|---|
| 0 | Odchudzic PIHA (prerekwizyt) | `modules/00-piha-slim.md` | — |
| 1 | SSO Forgejo-OIDC (decyzja+wzorzec) | `modules/01-sso-forgejo-oidc.md` | — |
| 2 | Paperless serwis (PIHA) | `modules/02-paperless-service.md` | 0,1 |
| 3 | Paperless OCR-worker (SOLARIA+fallback) | `modules/03-paperless-ocr-worker.md` | 2 |
| 4 | Nextcloud (WebDAV+OIDC) | `modules/04-nextcloud.md` | 0,1 |
| 5 | Ingest -> koperta | `modules/05-documents-ingest.md` | 2,4 |

Kazdy modul = samodzielny spec do puszczenia CC ("czytaj i implementuj krok po kroku").

---

## Ingest -> koperta (warstwa 2, wspolna dla obu zrodel)

Kazdy dokument -> koperta KB:
- `source` = `nextcloud` | `paperless`
- `id` = stabilny (Paperless doc-id | Nextcloud file-id+etag)
- `ts` = data dokumentu (Paperless wykrywa z tresci! lepsze niz mtime)
- `raw_ref` = Nextcloud: sciezka do KOPII w archiwum KB | Paperless: referencja doc-id
- `entities[]` = OCR-text + correspondent + tags (z Paperless API)

## Graf encji (warstwa 3, cienki start)
- **correspondent** (kto wystawil dokument) = encja -> link do maili (ten sam nadawca
  w mailu i fakturze = ta sama encja). PIERWSZY cross-source link (dowod zasady kb-00 #7).
- data dokumentu = klucz czasowy do zlaczen spatio-temporalnych.

## Domkniecie dlugu z maili
Faza-2-zalacznikow (70k zalacznikow / 15.4GB z importu Gmaila): faktury/umowy/PDFy
routuja do Paperless (jego OCR + correspondent-detection), NIE osobny pipeline.
Realizowane po modulach 2-3 (Paperless dziala) jako job w module 5.

---

## OTWARTE kwestie

- **Nextcloud host** — PIHA (ciasno) czy SOLARIA (drive nie musi byc 24/7 tak twardo
  jak indeks KB)? Do rozstrzygniecia przy module 4. Wstepnie: rozwazyc SOLARIA, bo
  Nextcloud ciezszy (PHP+baza+storage sync) niz Paperless-serwis.
- **Sizing OCR-batch** — ile trwa OCR 70k zalacznikow na SOLARIA, czy dzielic na partie.
- **Backup Paperless** — gdzie (PIHA NVMe? SOLARIA? offsite?), jaka retencja. Warunek
  brzegowy hybrydy — do zaprojektowania w module 2.