Architecture

Clean dependency direction

The package follows a dependency rule: the inner business layers do not depend on web frameworks, database drivers, HTTP clients, or documentation tooling.

presentation  ──► application  ──► domain
                     ▲              ▲
                     │              │
             infrastructure ────────┘
                     ▲
                     │
               composition root

Layer	Package	Responsibility
Domain	domain	Entities, value validation, pipeline invariants, matching policies, and port protocols.
Application	application	Commands and queries that coordinate workflow rules through ports.
Infrastructure	infrastructure	MySQL persistence, deterministic demo catalog, Core HTTP client, and runtime configuration.
Presentation	presentation	Versioned JSON API routes and schema validation.
Composition root	main.py	Creates concrete adapters, wires dependencies, and mounts generated documentation.

Why no in-application authentication?

This service is deliberately deployed as a private subsystem. The surrounding deployment network is responsible for access control; the application receives an explicit actor in every mutating request so the operational record remains attributable without pretending to be a public account system.

Extending with ML

Future model work belongs behind the ExtractionEngine port. An adapter receives only an opaque EvidenceReference and must return a provenance-preserving ReviewPacket. The default LockedExtractionEngine raises an explicit error for every real-evidence request. An approved Python adapter may replace it only after model-governance acceptance; it cannot bypass provenance, matching, review, or Core receipt policy.