# 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.