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. AISystem is the 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 aigerm.

The governance spine

flowchart TD
  Entity[Entity]
  Sys[AISystem]
  UC[AIUseCase]
  DS[DataSource]
  RA[RiskAssessment]
  ER[EthicalRisk]
  EPA[EthicalPrincipleAssessment]
  LCA[LegalComplianceAssessment]
  Ctl[Control]
  HOC[HumanOversightControl]
  TO[TransparencyObligation]
  EvR[EvidenceRequirement]
  EvS[EvidenceSubmission]
  AG[ApprovalGate]
  MM[MonitoringMetric]
  MO[MonitoringObservation]
  Inc[AdverseOutcomeIncident]
  FC[FeedbackComplaint]
  Chg[AIChange]
  TR[TrainingRequirement]
  TC[TrainingCompletion]
  Ret[RetirementPlan]

  Entity --> Sys
  Sys --> UC
  Sys --> DS
  Sys --> RA
  UC --> RA
  RA --> ER
  RA --> EPA
  Sys --> LCA
  ER --> Ctl
  Sys --> Ctl
  Ctl --> HOC
  Sys --> TO
  Sys --> EvR
  EvR --> EvS
  Sys --> AG
  Sys --> MM
  MM --> MO
  Sys --> Inc
  Sys --> FC
  Inc --> FC
  Sys --> Chg
  Sys --> TR
  TR --> TC
  Sys --> Ret

How to read it

  • AISystem is the hub. Use cases, data, assessments, controls, approval, monitoring, incidents, change and retirement all hang off it; the viewer lets you hide those hub edges to see local structure.
  • Assessment drives ethics & controls. A RiskAssessment produces EthicalRisks and per-principle EthicalPrincipleAssessments; a risk is mitigated by a Control (and, where decisions affect people, a HumanOversightControl).
  • Approval rests on evidence. EvidenceRequirement/EvidenceSubmission back the ApprovalGate decision (approve / conditional / reject).
  • Operation is monitored. MonitoringMetrics with thresholds produce MonitoringObservations (warning/breach); AdverseOutcomeIncidents and FeedbackComplaints capture harms — a complaint can link its incident.
  • Change & retirement stay governed. An AIChange may require reassessment; a RetirementPlan decommissions with a confirmation checklist.

Backing data (denormalised for display)

Each foreign key carries a denormalised <fk>_name display column so lists read in plain language (e.g. a Control shows the ethical risk it mitigates; a complaint shows its linked incident) without a join at read time — the house style for these apps.