Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

2026-10-01 01:34:21 +02:00
commit 7ca726caf2
@@ -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.