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. Campaign 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 scrm.

The readiness spine

flowchart TD
  Site[SiteRef]
  Camp[Campaign]
  Scope[ScopeItem]
  CWP[CampaignWorkPackage]
  Dep[Dependency]
  Req[ReadinessRequirement]
  Mob[ContractorMobilisation]
  MS[CampaignMilestone]
  Snap[ReadinessSnapshot]
  Chg[ScopeChange]

  Site --> Camp
  Camp --> Scope
  Scope --> CWP
  Camp --> CWP
  CWP --> Req
  CWP --> Dep
  Camp --> Dep
  Camp --> Mob
  Camp --> MS
  Camp --> Snap
  Camp --> Chg
  Scope --> Chg

(The Integration model — ExternalRecordLink — sits beside this spine and carries the cross-app links rather than local foreign keys, so it is omitted from the flow. The campaign's work orders and materials, which the work applications own, are CampaignWorkOrder and CampaignMaterial.)

How to read it

  • Campaign is the hub. A site hosts campaigns; almost everything else hangs off the campaign. The diagram viewer lets you hide those hub edges to see the local structure of each area.
  • Readiness is a four-step chain: a scope item is brought in → a campaign work package is created to deliver it → each package carries one or more readiness requirements (material, labour, contractor, permit, isolation, …) → a readiness snapshot rolls the whole campaign up into READY / AT_RISK / NOT_READY.
  • Dependencies order the packages. A Dependency links a predecessor work package to a successor (finish-start, access, resource, material, …); an unsatisfied dependency keeps a package from being ready.
  • Scope discipline is explicit. A ScopeChange records any add/defer/remove against a scope item, and CampaignMilestone tracks the scope-freeze and material-freeze gates.

The cross-app golden thread

SCRM is a campaign-role member of the Work & Supply network. It does not own materials, work execution or procurement — it references them by canonical_ref and reads their state:

  • A ScopeItem references an mwem work package — scope:sd-p101 is drawn from workpkg:wp-1001, and its CampaignWorkPackage carries the same external_work_package_canonical_ref.
  • A ReadinessRequirement on that package tracks material:brg-6208 (bearing BRG-6208). That bearing is short in msam (materials) and on order in psam (procurement), so the requirement sits NOT_READY and the package is only PARTIAL.
  • ContractorMobilisation references psam suppliers (supplier:site-services, supplier:heat-transfer-co); the same supplier ref appears on the E-301 contractor readiness requirement.
  • The result rolls up into the campaign's ReadinessSnapshot — AT_RISK: WP-1001 blocked on bearing BRG-6208 delivery; E-301 contractor not yet confirmed.

That single bearing shortage — visible in msam and psam, referenced here by a shared canonical_ref — is what turns an otherwise on-track shutdown at-risk, which is the point the demo network is built to show.

Backing data (denormalised for display)

Each foreign key carries a denormalised <fk>_name display column so lists read in plain language (e.g. a CampaignWorkPackage row shows its campaign title and scope-item title, a Dependency shows its predecessor and successor package titles) without a join at read time — the house style for these apps.