Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

docs/01_ARCHITECTURE/DATA_FLOWS.md

@@ -0,0 +1,29 @@
+# Data Flows
+
+## Application search
+
+1. Credential authenticeren en service-accountstatus controleren.
+2. Requested spaces syntactisch valideren.
+3. Effective spaces berekenen: `requested ∩ granted ∩ active ∩ policy-compatible`.
+4. Query normaliseren zonder semantisch betekenisverlies.
+5. Exacte identifiers detecteren en dense/sparse inputs maken.
+6. Qdrantfilters volledig server-side construeren.
+7. Kandidaten fusioneren via RRF, de-dupliceren en groeperen.
+8. Citations uit authoritative metadata materialiseren.
+9. Audit/metrics opslaan volgens privacybeleid.
+
+## Source publication
+
+1. Connector maakt source snapshot en cursor.
+2. Content hash identificeert unchanged/new/changed/deleted.
+3. Nieuwe bytes worden immutable opgeslagen.
+4. Securityclassificatie en quarantine gate.
+5. Parser maakt canonical document en extraction report.
+6. Chunker maakt deterministische chunk-ID's.
+7. Embeddingprofiel maakt vectors; index build blijft niet-actief.
+8. Structurele, count- en samplevalidatie.
+9. Databasepublicatie en indexalias omschakelen binnen gecoördineerde state transition.
+
+## Deletion
+
+Een bronverwijdering maakt de actieve versie onmiddellijk onvindbaar via authoritative statusfilter. Fysieke Qdrant- en blobverwijdering volgt asynchroon volgens retentiebeleid.

docs/01_ARCHITECTURE/DEPLOYMENT_TOPOLOGY.md

@@ -0,0 +1,31 @@
+# Deployment Topology
+
+## Development
+
+Docker Compose levert app, worker, PostgreSQL en Qdrant. Ollama is een optioneel profiel. Alleen app publiceert een hostpoort.
+
+## Unraid productie
+
+```text
+Nginx Proxy Manager / Authentik
+             |
+       ragcore-app:8080
+             |
+     internal Docker network
+    /        |          worker   PostgreSQL    Qdrant     Ollama
+```
+
+- PostgreSQL, Qdrant en Ollama publiceren geen internet- of LAN-poort via deze stack.
+- Actieve PostgreSQL/Qdrant-volumes gebruiken directe poolpaden zoals `/mnt/cache/appdata/ragcore/...` of `/mnt/<pool>/...`, niet `/mnt/pool/...`.
+- Back-ups en snapshots mogen naar `/mnt/pool/backups/ragcore` worden gekopieerd nadat ze consistent zijn geëxporteerd.
+- Containers draaien non-root, read-only waar mogelijk, met `no-new-privileges`.
+
+## Failure modes
+
+| Failure | Gedrag |
+|---|---|
+| Ollama down | `/search` en `/context` blijven beschikbaar; `/answers` geeft provider unavailable |
+| Qdrant down | API blijft live maar retrieval-readiness faalt |
+| Worker down | Bestaande actieve kennis blijft zoekbaar; nieuwe jobs wachten |
+| PostgreSQL down | readiness faalt; geen request dat autorisatie vereist wordt uitgevoerd |
+| Blobstore tijdelijk down | search op reeds geïndexeerde tekst kan doorgaan; documentopen/download faalt expliciet |

docs/01_ARCHITECTURE/MODULE_BOUNDARIES.md

@@ -0,0 +1,30 @@
+# Module Boundaries
+
+## Dependency rule
+
+```text
+api/web -> application -> domain
+worker  -> application -> domain
+infrastructure -> application ports + domain
+```
+
+`domain` importeert geen FastAPI, SQLAlchemy, Qdrant, Docling of provider-SDK. `application` definieert protocols/ports en use cases. `infrastructure` implementeert deze ports.
+
+## Modules
+
+| Module | Verantwoordelijkheid | Mag niet |
+|---|---|---|
+| `domain` | Entiteiten, value objects, policies, state machines | I/O of frameworks gebruiken |
+| `application` | Use cases, transacties, ports, authorization decisions | HTTP- of opslagdetails kennen |
+| `infrastructure` | PostgreSQL, Qdrant, blobs, providers, connectors | Businessbeleid bepalen |
+| `ingestion` | Pipelineactiviteiten en parsers | Versies rechtstreeks publiceren zonder gate |
+| `retrieval` | Query, fusion, rerank, context, answerability | Grants vertrouwen uit requestinput |
+| `generation` | Modelrouting en grounded output | Direct acties uitvoeren |
+| `evaluation` | Datasets en metrics | Productiedata ongemaskeerd exporteren |
+| `api` | HTTP-validatie en problem responses | Domeinlogica in routes stoppen |
+| `web` | Admin en Query Lab | Rechtstreeks databasequeries uitvoeren |
+| `platform` | Config, logging, telemetry, wiring | Domeinbeslissingen bevatten |
+
+## Import enforcement
+
+Architectuurtests inspecteren imports. Circular dependencies en verboden imports laten CI falen.

docs/01_ARCHITECTURE/SYSTEM_ARCHITECTURE.md

@@ -0,0 +1,56 @@
+# System Architecture
+
+## Stijl
+
+V1 is een **modulaire monoliet** met twee procesrollen uit hetzelfde codebase/image:
+
+- `ragcore-app`: HTTP API, beheerinterface, retrieval- en answerorchestratie;
+- `ragcore-worker`: ingestion-, synchronisatie-, embedding- en onderhoudsjobs.
+
+Externe stateful services zijn PostgreSQL en Qdrant. Ollama is optioneel en kan reeds centraal bestaan.
+
+```text
+Clients / MCP / UI
+        |
+  Reverse proxy + OIDC
+        |
+    ragcore-app ---------------- Model provider
+       |          |    \---- Qdrant (derived retrieval index)
+       |
+   PostgreSQL (control plane + jobs)
+       |
+   ragcore-worker ---- immutable blobs / parsed artifacts
+```
+
+## Waarom geen microservices
+
+- Eén server en beperkte initiële belasting.
+- Eenvoudiger transacties, upgrades, debugging en restore.
+- Minder netwerk- en deploymentcontracten.
+- Modulaire grenzen maken latere extractie mogelijk wanneer metingen dat rechtvaardigen.
+
+## Requestpaden
+
+### Search
+
+`API -> authorization -> query analysis -> dense/sparse retrieval -> hybrid RRF-fusion -> citations -> response`
+
+V1 voert geen reranker uit: de gefuseerde volgorde is de productieranking.
+Een toekomstige optionele reranker vereist een apart, gevalideerd provider- en
+evaluatiebesluit.
+
+### Answer
+
+`Search -> context assembly -> answerability -> provider policy -> grounded generation -> claim/citation validation -> response`
+
+### Ingestion
+
+`source sync -> immutable acquisition -> security gate -> parse -> normalize -> chunk -> embed -> shadow index -> validate -> publish`
+
+## Betrouwbaarheidsgrenzen
+
+- Internet, uploads en repositories zijn onbetrouwbare input.
+- Reverse proxy/OIDC valideert mensidentiteit; RAGCore autoriseert resources.
+- Service tokens identificeren applications maar geven alleen expliciete grants.
+- Qdrant is niet publiek en vertrouwt alleen RAGCore.
+- Modelproviders ontvangen uitsluitend policy-toegestane context.