02 — System Diagram

🔍 Open the Interactive Diagram Viewer — pan, mouse-wheel zoom, fit-to-screen, full-screen, per-area tabs, the full ERD, and a focus mode that draws one model and its neighbours at a chosen depth. Recommendation is a hub table, so its links can be hidden to declutter the overview.

Regenerate the viewer after any DSL, menu_config.yaml or diagram_config.yaml change: python scripts/build_diagram_viewer.py area.

The assurance spine

flowchart TD
  Entity[Entity]
  Report[AuditReport]
  Rec[Recommendation]
  Resp[ManagementResponse]
  Act[ImplementationAction]
  MS[Milestone]
  ER[EvidenceRequirement]
  EV[EvidenceSubmission]
  VT[ValidationTest]
  Val[EvidenceValidation]
  Exc[Exception]
  Risk[Risk]
  Dec[AssuranceDecision]
  CR[ClosureRequest]
  CA[ClosureApproval]
  SH[StatusHistory]

  Entity --> Rec
  Report --> Rec
  Rec --> Resp
  Rec --> Act
  Act --> MS
  Rec --> ER
  Act --> ER
  ER --> EV
  Rec --> EV
  EV --> Val
  VT --> Val
  Rec --> Val
  Val --> Exc
  Rec --> Exc
  Exc --> Risk
  Rec --> Risk
  Exc --> Dec
  Rec --> Dec
  Rec --> CR
  CR --> CA
  Rec --> SH

How to read it

  • Recommendation is the hub. Almost everything hangs off it; the diagram viewer lets you hide those hub edges to see the local structure of each area.
  • Evidence is a three-step chain: a requirement says what is needed, a submission provides it, and an independent validation applies a reusable test to judge it sufficient / insufficient.
  • Exceptions gate closure. An Exception with closure_blocking = true must be resolved before a ClosureApproval can be APPROVED.
  • Closure is two-part: a ClosureRequest (declaring completion) and an independent ClosureApproval (the authorised outcome).
  • StatusHistory is the audit trail of the recommendation's state transitions.

Backing data (denormalised for display)

Each foreign key carries a denormalised <fk>_name display column so lists read in plain language (e.g. a Recommendation row shows its report title and entity name; an Exception shows the recommendation title and the validator name) without a join at read time — the house style for these apps.