Architecture

How the service is structured and why. Roughly ordered C4-style — start at the top for the big picture and zoom in.

Doc	When you need it
Architecture style	Hexagonal layout, layer rules, why we picked this pattern
System context	The app and its external neighbours (LLM provider, Presidio, Postgres, callers)
Components	Ports, adapters, the application services, the composition root
Cross-cutting concerns	Anonymisation, tracking, error handling, logging — concerns that span layers
Data model	Domain models and persistence schema
Prompt envelope and guardrails	Three-constant system message, XML-style envelope, escape helper, judge call contract for POST /v1/analyze-bulk
Hierarchical analysis	The mode=hierarchical embed → cluster → map → reduce algorithm for large corpora, in prose with flow and sequence diagrams

For decision history (why we chose what we chose), see the architecture decision records.