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. Material and Material Demand are hub tables, so their 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 msam.

The materials-readiness spine

flowchart TD
  Site[SiteRef]
  Loc[StockLocation]
  Mat[Material]
  Pos[StockPosition]
  Dem[MaterialDemand]
  Res[Reservation]
  Short[SupplyShortage]
  Stage[StagingRecord]
  Rcpt[MaterialReceipt]
  RU[RepairableUnit]
  RC[RepairCycle]

  Site --> Loc
  Mat --> Pos
  Loc --> Pos
  Mat --> Dem
  Dem --> Res
  Pos --> Res
  Dem --> Short
  Dem --> Stage
  Mat --> Rcpt
  Loc --> Rcpt
  Mat --> RU
  RU --> RC

(The two Integration tables — ExternalRecordLink and EventOutbox — sit off this spine; they carry cross-app links and the domain-event outbox, not material flow.)

How to read it

  • Reference first. A SiteRef owns StockLocations; a Material (the master) is the anchor for everything else. A StockPosition is one material at one location — its on-hand / reserved / available balance.
  • Demand drives the lifecycle. A MaterialDemand (from a work package, shutdown, project or replenishment) is worked toward ready down one of two paths:
  • Met from stock → a Reservation holds quantity from a StockPosition, then a StagingRecord moves it to a readiness location → STAGED → READY.
  • Not met → a SupplyShortage is raised; when procurement_required it is REFERRED out to procurement, and later a MaterialReceipt brings goods back in.
  • Repairables loop. A RepairableUnit (a serialised/rotable spare) runs through one or more RepairCycles: removed → sent for repair → returned → accepted.

The cross-app golden thread

MSAM is the materials member of the Work & Supply network. The seeded scenario carries one demand across three apps:

  1. mwem raises work demand demand:wp-1001-brg for material:brg-6208 (work package workpkg:wp-1001) — the orchestrator upserts it into MSAM as a MaterialDemand.
  2. msam finds the bearing's StockPosition at zero available, so the demand goes SHORT and a SupplyShortage is raised with procurement_required = true.
  3. The shortage is REFERRED — the hand-off to psam, which turns it into a PurchaseRequirement (network route WS-MATERIALS-PROC).

The material master mirrors the amia/mwem references: material:* is MSAM-owned but shared verbatim, and site:* mirrors the amia site master — so the same identifiers name the same real-world thing in every app.

Backing data (denormalised for display)

Each foreign key carries a denormalised <fk>_name-style display column so lists read in plain language (a StockPosition shows its material and location names; a Reservation shows its demand and stock-position refs) without a join at read time — the house style for these apps.