01 — Quick Reference

Run it

python server/run.py msam          # http://localhost:5083

(Re)seed the sample data

python -m codegen.cli seed msam            # load demo rows (skips if data present)
python -m codegen.cli seed msam --reset     # wipe and reload the demo rows

Regenerate code & the diagram viewer

python -m codegen.cli all msam              # validate → models → controllers → menu/config
python scripts/build_diagram_viewer.py msam # rebuild docs_portal/asset/system_diagram_viewer.html

Re-run the viewer build after any change to schema/msam.dsl, schema/menu_config.yaml or schema/diagram_config.yaml.

Group Models
Reference Data SiteRef · Material · StockLocation
Stock & Staging StockPosition · Reservation · StagingRecord
Demand & Supply MaterialDemand · SupplyShortage · MaterialReceipt
Repairables RepairableUnit · RepairCycle
Integration ExternalRecordLink · EventOutbox

Every model (13) — one line each

Model It records Key foreign keys
SiteRef A site materials/stock belong to —
Material The material master record —
StockLocation A store at a site SiteRef
StockPosition On-hand/reserved/available balance at a location Material, StockLocation
MaterialDemand A requirement for material (work/shutdown/repl.) Material (local, nullable)
Reservation Stock held against a demand MaterialDemand, StockPosition
SupplyShortage An unmet demand (may be referred to procurement) MaterialDemand
MaterialReceipt Goods received against a PO Material, StockLocation
StagingRecord Material staged to a readiness location MaterialDemand
RepairableUnit A repairable/rotable serialised unit Material
RepairCycle One remove→repair→return→accept cycle RepairableUnit
ExternalRecordLink Link to an external-system record — (cross-app, by canonical_ref)
EventOutbox Domain events published to the network —

Status vocabularies

  • Material type: CONSUMABLE · SPARE · CRITICAL_SPARE · REPAIRABLE · ROTABLE · SERIALISED · PROJECT
  • Criticality: LOW · MEDIUM · HIGH · CRITICAL
  • Replenishment strategy: MIN_MAX · REORDER_POINT · WORK_SPECIFIC · JIT · CONSIGNMENT · VMI · REPAIR_EXCHANGE · MANUAL
  • Demand status: OPEN → ALLOCATING → RESERVED → SHORT → ORDERED → RECEIVED → STAGED → READY · CANCELLED
  • Demand priority: ROUTINE · HIGH · CRITICAL
  • Reservation status: HELD · RELEASED · ISSUED · CANCELLED
  • Shortage status: OPEN · REFERRED · MITIGATED · RESOLVED
  • Receipt inspection: NOT_REQUIRED · PENDING · ACCEPTED · REJECTED
  • Readiness (staging): NOT_STAGED · PARTIAL · STAGED · READY
  • Repairable unit status: SERVICEABLE · INSTALLED · REMOVED · AWAITING_INSPECTION · UNDER_REPAIR · TESTING · QUARANTINED · SCRAPPED
  • Repair cycle status: OPEN · SENT · REPAIRING · RETURNED · ACCEPTED · REJECTED · CLOSED
  • Authority mode: LOCAL · EXTERNAL_ERP (ExternalRecordLink also SHARED)

Demo data set (32 rows)

Model Rows Model Rows
SiteRef 3 SupplyShortage 1
Material 6 MaterialReceipt 1
StockLocation 3 StagingRecord 2
StockPosition 6 RepairableUnit 1
MaterialDemand 5 RepairCycle 1
Reservation 3 ExternalRecordLink · EventOutbox 0

Cross-app canonical_ref conventions

MSAM is a Work & Supply network member. canonical_ref values are stable, never reused, and shared verbatim with sibling apps so records join across app boundaries. Cross-app references are strings, not database foreign keys.

Prefix Owner Meaning in MSAM
material:* msam Material master — the cross-app material identity (e.g. material:brg-6208)
demand:* msam MaterialDemand — upsert target for mwem work demand (e.g. demand:wp-1001-brg)
site:* amia SiteRef mirror of the shared site master
workpkg:* mwem MaterialDemand.source_canonical_ref — the work package driving the demand
po:* psam MaterialReceipt.purchase_order_canonical_ref — the PO goods were received against
supplier:* psam RepairCycle.repair_supplier_canonical_ref — the repair vendor

Golden thread: mwem raises demand:wp-1001-brg for material:brg-6208 (WP-1001) → MSAM finds zero available → the demand goes SHORT and the shortage is REFERRED to psam for procurement.