00 — Overview

Demonstration prototype. MSAM is a member of the Work & Supply reference network — a demonstration multi-app integration where an orchestrator routes events between sibling apps (amia asset master, mwem work execution, msam materials, psam procurement, scrm shutdown/campaign, plus cwia, psba and soim). Apps share stable canonical_ref identifiers so records link across apps. Every material, stock position, demand and repair record in the demo data is fictional — the data illustrates the model and the cross-app workflow only.

What MSAM is

The Materials & Spares Assurance Manager answers one operational question for maintenance and shutdown work: is the material actually there and ready when the job needs it? A demand is not "satisfied" because a part exists somewhere — it is satisfied when stock is reserved, physically staged at a readiness location, and marked ready; and when it cannot be met from stock it becomes a shortage that is referred out to procurement. MSAM holds the material master, the stock positions, and the full demand → reserve/stage-or-shorten → receipt → readiness chain so material readiness is always demonstrable, and it tracks repairable units through their repair cycles.

The domain

Maintenance materials management has three hard parts: availability (what is on hand, reserved and available, and where), traceability of demand (which work package or campaign a demand serves, and whether it is reserved, short, staged or ready), and the repair-exchange loop for repairable/rotable spares (remove → send for repair → return → accept). MSAM models all three, and — as a network member — exposes them across apps: work demand arrives from mwem, material and asset masters mirror amia/mwem references, and shortages are referred to psam for procurement.

The 13 models by area

Reference Data (3) - SiteRef — a site the stock and materials belong to (mirrors the shared site:* master). - Material — the material master record; carries type, criticality and replenishment strategy. A cross-app master keyed on material:*. - StockLocation — a physical/consignment store at a site.

Stock & Staging (3) - StockPosition — on-hand / reserved / available balance for a material at a location, with min/max/reorder levels and local-vs-ERP authority. - Reservation — stock held against a demand from a specific stock position (held / issued / released / cancelled). - StagingRecord — the physical staging of demanded material to a readiness location, with a readiness status.

Demand & Supply (3) - MaterialDemand — a requirement for material from a work package, shutdown, project or replenishment; carries priority and lifecycle status (OPEN → RESERVED / SHORT → STAGED → READY). A cross-app upsert target keyed on demand:*. - SupplyShortage — a demand that cannot be met from stock; when procurement_required it is REFERRED out to procurement. - MaterialReceipt — goods received into a location against a purchase order, with inspection status.

Repairables (2) - RepairableUnit — a repairable/rotable serialised unit and its current status and location. - RepairCycle — one removal → repair → return → accept cycle for a repairable unit, with a repair supplier reference.

Integration (2) - ExternalRecordLink — a link from a local record to its counterpart in an external system (e.g. ERP), with authority mode and sync state. - EventOutbox — the durable outbox of domain events published to the network (currently unseeded; the runtime publisher is Phase 2).

The demo scenario

A shutdown-style materials picture across three sites, 32 rows over 11 of the 13 models (the two Integration tables carry no demo rows). The scenario shows every branch of the readiness spine:

  • BRG-6208 (Bearing 6208) — demand demand:wp-1001-brg for work package WP-1001 hits a zero on-hand stock position, so it is SHORT; the shortage short:brg-wp1001 is procurement_required = true and REFERRED — the cross-app hand-off to psam.
  • GSKT-CS-4IN (gasket) — demand for WP-1002 is reserved (4 held), staged and READY; a matching receipt (receipt:gskt-2026-10, PO po:5002) was ACCEPTED into the main store.
  • CPLG-ELEM (coupling) — demand for WP-1004 is reserved (ISSUED) and STAGED at a laydown bay.
  • SEAL-MECH-2IN (mechanical seal) — a REPLENISHMENT demand reserved from a consignment cabinet (RESERVED).
  • TUBE-BDL-E301 (tube bundle) — a REPAIRABLE unit ru:tube-e301-sn1 is UNDER_REPAIR at a supplier workshop; its repair cycle repair:tube-e301-c1 is REPAIRING (removed → sent to supplier:heat-transfer-co), while its work demand sits at ORDERED.

Together these show a shortage referred to procurement, a fully staged/ready line, an issued reservation, a consignment replenishment, and a repairable out on its repair cycle — the whole materials-readiness model in one coherent, fictional data set.