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. WorkOrder 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 work_management.

The work spine

flowchart TD
  TPL[MaintenanceTemplate]
  WO[WorkOrder]
  TASK[WorkTask]
  ASG[WorkAssignment]
  TIME[WorkTimeEntry]
  MR[WorkMaterialRequirement]
  TOOL[ToolRequirement]
  DEP[WorkDependency]
  SAFE[SafetyDocumentReference]
  ISO[IsolationReference]
  RC[RemovedComponent]
  IC[InstalledComponent]
  EV[Evidence]
  TR[TestResult]
  RTS[ReturnToService]
  VER[Verification]
  CL[Closeout]
  SH[WorkStatusHistory]

  TPL --> WO
  WO --> TASK
  WO --> ASG
  WO --> TIME
  WO --> MR
  WO --> TOOL
  WO --> DEP
  WO --> SAFE
  WO --> ISO
  WO --> RC
  WO --> IC
  WO --> EV
  EV --> TR
  WO --> RTS
  RTS --> VER
  WO --> CL
  WO --> SH

Material: how a requirement gets its answer (R1 / R2)

sequenceDiagram
  participant W as Work Management
  participant O as Orchestrator
  participant I as Inventory
  participant P as Purchasing
  W->>W: save Material Requirement (MR-…)
  W->>O: work.material_requirement_created
  O->>I: deliver (subscription)
  I->>I: reserve stock, or record unavailable
  alt in stock (R2)
    I->>O: inventory.item_reserved
    O->>W: deliver
    W->>W: requirement reserved, RES-… filled in
  else none in stock (R1)
    I->>O: inventory.item_unavailable
    O->>W: deliver
    W->>W: requirement unavailable, order awaiting_parts
    O->>P: deliver (purchasing need)
  end

The event leaves Work Management in the same database transaction as the requirement itself, so a saved requirement is never lost and never announced twice. If Inventory is down, delivery retries on a schedule (2 s … 10 min) and then becomes a dead letter for an operator to retry; a repeated delivery is recognised and not processed twice.

Work order lifecycle

stateDiagram-v2
  [*] --> draft
  draft --> planned
  planned --> awaiting_parts: critical material unavailable
  planned --> assigned
  awaiting_parts --> assigned: planner, once material is in
  assigned --> in_progress
  in_progress --> suspended
  suspended --> in_progress
  in_progress --> ready_for_test
  ready_for_test --> returned_to_service
  returned_to_service --> ready_for_verification
  ready_for_verification --> closed
  closed --> [*]