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. WorkPackage 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 mwem.

The work-execution spine

flowchart TD
  Site[SiteRef]
  Asset[AssetRef]
  WR[WorkRequirement]
  WP[WorkPackage]
  LR[LabourRequirement]
  MR[MaterialRequirement]
  TR[ToolRequirement]
  AR[AccessRequirement]
  WO[WorkOrder]
  EX[ExecutionRecord]
  VR[VerificationRecord]
  RTS[ReturnToService]

  Site --> Asset
  Site --> WR
  Asset --> WR
  WR --> WP
  WP --> LR
  WP --> MR
  WP --> TR
  WP --> AR
  WP --> WO
  WO --> EX
  WO --> VR
  WO --> RTS

(The Integration group — ExternalRecordLink — carries no database foreign keys; it links to other systems by string canonical_ref, so it sits outside the FK spine above.)

How to read it

  • WorkPackage is the hub. A requirement becomes a package; the package fans out to its labour, material, tool and access requirements, then to the work order that executes it. The diagram viewer lets you hide those hub edges to see local structure.
  • The lifecycle runs left-to-right down the spine: WorkRequirement (a need) → WorkPackage (planned, made ready) → WorkOrder (authority to execute) → ExecutionRecord → VerificationRecord → ReturnToService.
  • Readiness is the gate. A package's readiness_state is only READY when its labour/material/tool/access requirements are confirmed; a work order should not be released while a MaterialRequirement is SHORT.
  • Authority is explicit. A WorkOrder runs LOCAL or EXTERNAL_ERP; when external, an ExternalRecordLink maps it to the system of record (e.g. a simsap MaintenanceOrder).

The cross-app golden thread

The demo's P-101 bearing shortage shows how the spine reaches beyond mwem via shared canonical_ref identifiers and the integration layer's outbox:

  • WP-1001's MaterialRequirement for material:brg-6208 is SHORT, so the package is BLOCKED / readiness PARTIAL.
  • That shortage emits work.material_required → msam raises a MaterialDemand, which emits material.procurement_required → psam raises a PurchaseRequirement (PR-1001 / PO-5001).
  • The same workpkg:wp-1001 also appears as scope in a scrm shutdown/campaign.
  • Meanwhile WP-1004 runs cleanly to ReturnToService APPROVED, with an ExternalRecordLink tying WO-1004 to a simsap ERP order.

Backing data (denormalised for display)

Each foreign key carries a denormalised <fk>_name display column so lists read in plain language (a WorkPackage shows its requirement title; a MaterialRequirement shows its package) without a join at read time — the house style for these apps.