oskar 00de8107ea feat(kb): przenosiny type=subsystem do kb/subsystems/ (18 plikow, bez SPLIT)

public (wzorce/schematy, bez IP/portow/sciezek hostow): observer,
capability-model, event-system, standards, agent-operating-procedures,
service-model, action-approval-model.

private: recon-multiagent, fleet-inventory, fleet-inventory-verify,
kb-mail-pillar, kb-documents-pillar, topology, agent-system.

deprecated (martwe stuby z 2026-04-15) — visibility private wg
rozstrzygniecia 6: access-model, core-stack, legacy-services-list, networking.

git mv + frontmatter, tresc nietknieta.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-04 16:58:04 +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: 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.

5.5 KiB Raw Blame History