oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/kb/subsystems/kb-documents-pillar.md
oskar 9128530589 fix(kb): 13 pozostalych odwolan do sciezek sprzed migracji 
Weryfikacja 0-odwolan z 01db57a liczyla tylko podzbior prefiksow — poza nim
zostalo 13 wskaznikow w plikach niemarkdownowych i w prozie dokumentow:

  docs/kb/modules/05-faza3-plan.md   -> kb/phases/kb-m5-faza3.md (2x systemd)
  docs/kb/modules/05-faza4-plan.md   -> kb/phases/kb-m5-faza4.md (kb-query app.js)
  docs/kb/modules/DECYZJE-*.md       -> kb/decisions/kb-dokumenty-otwarte.md
  docs/backlog.md (npm panel admina) -> kb/decisions/backlog-aktywne.md
  docs/backlog/ (uid/gid floty)      -> kb/decisions/backlog-uid-gid-flota.md
  docs/kb/modules/0X-*.md            -> kb/phases/kb-m*.md
  docs/incidents/2026-07-30-*.md     -> kb/incidents/ (3x node-agent)
  docs/architecture/RECON-multi*.md  -> kb/subsystems/recon-multiagent.md
  jobs/deploy-runner/README.md       -> kb/services/job-deploy-runner.md

Wyjatek zamierzony: `docs/kb/modules/05-faza3-pilot-streszczen.md` w §11 planu
fazy 3 to nazwa artefaktu, ktory nigdy nie powstal — przepiety na docelowa
konwencje (kb/phases/kb-m5-faza3-pilot-streszczen.md), zeby przyszly plik
wyladowal w nowym drzewie, a nie w skasowanym katalogu.

Weryfikacja: skan po 67 sciezkach zmigrowanych w tej galezi (git grep -F na
kazdej) = 0 trafien poza docs/sessions (logi historyczne, celowo nietkniete);
0 martwych linkow markdown na 190 plikach; check_okf.py 190/190 ZGODNE.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 17:02:12 +02:00

5.5 KiB
Raw Blame History

okf type visibility status updated links
0.1 subsystem private active 2026-07-01

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: kb/phases/kb-m*.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.