Reference Architecture: Auditable Case Review

This chapter turns the capstone into implementation contracts. It is still a teaching architecture, not a production-ready product. The point is to show what the system would need before a real team could build it.

Contract Fixture

The concrete contract lives in:

fixtures/contracts/case_review_contracts.json

It defines:

• API endpoints
• domain events
• data tables
• capstone variants
• required fields
• risk levels
• approval requirements
• tenant-scoping requirements

Validate it with:

python3 examples/reference-architecture/validate_contracts.py \
  fixtures/contracts/case_review_contracts.json

The same fixture can be translated into implementation-facing contracts such as endpoint metadata, event schemas, and variant schemas. The learner-facing lesson is that architecture rules should be concrete enough to become boundary contracts.

Run a local API that enforces the same request contracts with:

python3 examples/reference-architecture/serve_contract_api.py

Smoke-test it with:

python3 examples/reference-architecture/smoke_contract_api.py

API Surface

The reference architecture starts with four API actions:

The important design choice is that critical endpoints require approval and carry an analyst-owned request shape. The model can help prepare the evidence packet, but it cannot satisfy the approval contract.

Domain Events

The reference events are:

CaseOpened
DocumentUploaded
EvidencePacketBuilt
RiskSignalGenerated
AnalystApproved

Each event has required fields. Model-owned events include prompt and model versions. Analyst-owned events include analyst identity and reason codes. This is how auditability becomes structural.

Data Tables

The minimal data model includes:

Every table carries tenant scope. The audit table is append-only. Evidence packets are versioned instead of overwritten. Outbox rows make async AI jobs recoverable.

Capstone Variant Contracts

The same fixture now includes three variant contracts:

Each variant records:

• forbidden model actions
• allowed human-owned transition path
• evaluation focus
• observability fields
• security controls
• economics metrics
• trust artifacts

This turns the capstone variants into checkable design objects. The prose says the model must not decide; the fixture makes that claim explicit with model_may_decide: false.

Contract Rules

The validator enforces a small set of architecture rules:

• medium and higher risk endpoints require tenant_id
• critical endpoints require approval
• model events require prompt_version and model_name
• analyst events require analyst_id
• domain events require case_id and occurred_at
• data tables require tenant scope
• data tables require constraints
• capstone variants require model_may_decide: false
• capstone variants require forbidden model actions and a human-owned path to an audit artifact

These rules are deliberately modest. They are enough to show the pattern: if a design rule matters, make it checkable.

Local API Example

The local API is intentionally small and dependency-free. It is not a production server. It teaches how contract rules appear at the boundary:

• unknown routes return route_not_found,
• missing required fields return contract_validation_failed,
• path parameters must match body fields,
• critical endpoints require X-Human-Approval: true,
• response payloads expose operation name, risk level, approval requirement, and typed response data.

This makes the human-control invariant tangible. A model can produce JSON, but the approval endpoint still refuses a critical transition unless the boundary receives an explicit human-approval signal.

Implementation Boundary

A real implementation would split this architecture into:

• HTTP/API DTOs
• domain types and transition functions
• persistence rows and migrations
• outbox publisher
• worker jobs
• model provider adapters
• analyst review UI
• audit export
• observability pipeline
• evaluation suite

Do not let provider DTOs, HTTP payloads, and database rows become the domain model. Convert at boundaries.

Extension Points

The first production expansion should add:

• contract tests for API handlers
• OpenAPI output from the endpoint contract
• JSON Schema for event payloads
• database migrations with constraints
• fixture-backed eval reports
• trace examples matching the observability fixture
• threat model coverage for every tool

The current fixture and local API are intentionally small. They prove that the architecture can become implementation-facing contracts without making the textbook pretend to be a complete framework.