Buurts Ecosysteem — Architectuur¶

Bijgewerkt: Sprint C (14 maart 2026)

Huidige staat (Sprint C)¶

[Claude Desktop / Cowork]
        ↓  CLAUDE.md (auto-load), .mcp.json
[Buurts MCP Server]                   ← Sprint 10 + C
  buurts_knowledge_search
  buurts_knowledge_ask
        ↓  intern HTTP (BackendClient)
[FastAPI backend — main.py]            ← Sprint 9 hardening
        ↓
[HubAgent — agents/hub.py]             ← orchestrator, Guardian Layer (Art. 5)
  ├─ ScoutAgent     (zoeken)
  ├─ CuratorAgent   (filteren + curate)
  └─ OllamaSynthesizer / MockSynthesizer
        ↓
[Safety Policy — safety/policy.py]     ← GREEN / YELLOW / RED
        ↓
[ZonedVectorStore — rag/vector_store.py]  ← Sprint A
  ├─ ChromaDB RED    (data/chromadb_red)
  ├─ ChromaDB YELLOW (data/chromadb_yellow)
  └─ ChromaDB GREEN  (data/chromadb_green)
        ↓
[DocumentRegistry — rag/document_registry.py]  ← SQLite
[SmartChunker — rag/chunker.py]                ← Sprint A, semantische chunks

Query data flow (request → response)¶

Gebruiker stelt vraag
  → MCP: buurts_knowledge_ask(query, domain?)
    → BackendClient.ask_question() → POST /ask
      → HubAgent.process()
        → ScoutAgent.search()
          → ZonedVectorStore.search(zone=GREEN/YELLOW)
            ← top_k chunks + metadata (UDS V2: zone, ldf_level, bron_type)
        → CuratorAgent.curate(chunks)
            ← gefilterde, gerangschikte chunks
        → OllamaSynthesizer.synthesize(query, chunks)
            ← antwoord tekst + bronverwijzingen
        → SafetyPolicy.evaluate(query + antwoord)
            ← safety_status: GREEN_ZONE / YELLOW_ZONE / BLOCKED
      ← FastAPI response: answer + sources + safety + confidence
    ← MCP tools.py: format_ask_response() → safety blok normalisatie
  ← Claude: antwoord + zone indicator aan gebruiker

Doelarchitectuur (Sprint B+)¶

[Zorgmedewerker interface — Sprint D+]
        ↓
[MCP Host: Claude Desktop / eigen agent]  ← Sprint C: config gereed
        ↓  MCP protocol (stdio)
[Buurts MCP Server]
  buurts_knowledge_search
  buurts_knowledge_ask
  buurts_ingest_document   ← Sprint B backlog
  buurts_list_library      ← Sprint B backlog
        ↓  intern HTTP
[FastAPI backend]
        ↓
[ZonedVectorStore (RED/YELLOW/GREEN)]
        ↓
[SharePoint connector]     ← Sprint B
[ChromaDB × 3 zones]
[Ollama / Cloud LLM]       ← beslissing #3 open

Vastgestelde keuzes¶

Beslissing	Keuze	Sprint	Reden
MCP implementatie	Python MCP SDK	10	Zelfde stack, officieel Anthropic
FastAPI	Blijft intact	—	MCP is laag erbovenop, geen vervanging
MCP tools MVP	knowledge_search + ask_question	10	Minimaal werkend eerst
Vector store	ChromaDB (3 geïsoleerde collecties)	A	Zone-isolatie: RED nooit bevraagd zonder expliciet
Chunker	SmartChunker als default	A	Semantische grenzen, 10% overlap
UDS metadata	V2 (zone, ldf_level, bron_type, domein)	A	Toekomstbestendig filtering
Claude config	CLAUDE.md + .mcp.json + .claude/settings.json	C	Auto-load context, zero-friction
Git	Trunk-based, feature branch per sprint	—	CI vereist groen op main

Openstaande beslissingen¶

#	Vraag	Blokkeert
1	SharePoint connector: productie-klaar of mock?	Sprint B
2	MCP host productie: eigen agent of UI framework?	Sprint B/D
3	Ollama: lokaal of cloud LLM voor productie?	Sprint D
4	LDF-level als filter in retrieval-stap?	Sprint B
5	Ethical Mirror: in code of via prompt?	Sprint D

Technische schuld¶

Item	Prioriteit	Sprint ontdekt
Policy-laag niet LDF-bewust (geen level-filtering bij retrieval)	Hoog	10
RED-zone abstain niet per endpoint geïmplementeerd in safety/gates.py	Hoog	10
Ethical Mirror (Art. 12) conceptueel maar niet in code	Medium	10
Hub is single point of failure voor ethiek-handhaving	Medium	10
Eval golden sets alleen Autisme domein	Laag	9
Geen structured logging (alleen JSON naar stdout)	Laag	C

Module-referentie (meest aangeraakte bestanden)¶

Module	Verantwoordelijkheid
`main.py`	FastAPI app, routers, DI-setup
`config.py`	Settings via pydantic-settings + .env
`agents/hub.py`	Orchestrator, Guardian Layer
`agents/curator.py`	Curatielogica, relevantie-filter
`agents/synthesizer.py`	Mock synthesizer (voor tests)
`agents/ollama_synthesizer.py`	Productie LLM synthesizer
`rag/vector_store.py`	ZonedVectorStore (3 ChromaDB collections)
`rag/chunker.py`	SmartChunker + DocumentChunker (legacy)
`rag/document_registry.py`	SQLite registry voor ingest tracking
`rag/sharepoint_connector.py`	SharePoint connector (Sprint B)
`safety/policy.py`	Zone-evaluatie (GREEN/YELLOW/RED)
`safety/gates.py`	Blocklist + allowlist checks
`mcp_server/server.py`	MCP server entry point
`mcp_server/tools.py`	Response formatters + safety-blok
`mcp_server/backend_client.py`	HTTP client naar FastAPI