System Diagram

The CSIM data model, mapped — 31 models, 109 relationships

🔍 For serious exploration, open the Interactive Diagram Viewer — pan, mouse-wheel zoom, fit-to-screen, full-screen, per-module tabs, the full 109-relationship ERD, and a focus mode that draws one model and its neighbours at a chosen depth. Person (42 links) and Organisation (15) are role columns that fan out to nearly everything, so the viewer hides those by default — a toggle brings them back. The diagrams below are the readable, static summary of the principal links only.

Architecture Overview

Seven areas mirror the sidebar menu. Every arrow means "one row of the left model is referenced by many rows of the right model".

flowchart LR
    subgraph REF["📚 Reference"]
        Organisation --> Site --> SiteArea
    end

    subgraph CTR["🏢 Contractors"]
        ContractorProfile
        ContractorDocument
        ContractorPerformanceReview
    end

    subgraph WRK["📄 Contracts & work"]
        Contract --> ContractRequirement
        Contract --> WorkPackage
        WorkPackage --> SubcontractorEngagement
        WorkPackage --> Mobilisation --> MobilisationChecklistItem
        WorkPackage --> Demobilisation
    end

    subgraph IFC["🔗 Interfaces & controls"]
        InterfaceRegister --> InterfaceHazard --> InterfaceControl
        InterfaceRegister --> InterfaceDecision
        CoordinationMeeting --> MeetingAttendance
    end

    subgraph PPL["👷 People & access"]
        Person --> PersonCompetency
        Person --> SiteInduction
        Person --> SiteAccessAuthorisation
        RoleRequirement
    end

    subgraph PLT["🚜 Plant"]
        ContractorPlant --> PlantSiteApproval
    end

    subgraph ASR["🔍 Assurance"]
        FieldAssuranceEvent --> AssuranceFinding
        AssuranceFinding --> StopWorkEvent
        Incident
        CorrectiveAction
    end

    Organisation --> Contract
    Organisation --> ContractorProfile
    Organisation --> ContractorPlant
    SiteArea --> WorkPackage
    WorkPackage --> InterfaceRegister
    WorkPackage --> CoordinationMeeting
    WorkPackage --> FieldAssuranceEvent
    WorkPackage --> Incident
    InterfaceControl --> AssuranceFinding
    AssuranceFinding --> CorrectiveAction
    Incident --> CorrectiveAction
    ContractorPerformanceReview --> CorrectiveAction
    Contract --> ContractorPerformanceReview

The Core Chain

Plan on the left, field evidence on the right. This is the diagram the application exists to make true.

erDiagram
    Contract ||--o{ WorkPackage : "contract_id"
    SiteArea ||--o{ WorkPackage : "site_area_id"
    WorkPackage ||--o{ WorkPackage : "parent_work_package_id"
    WorkPackage ||--o{ InterfaceRegister : "work_package_id"
    WorkPackage ||--o{ InterfaceRegister : "other_work_package_id"
    SiteArea ||--o{ InterfaceRegister : "affected_area_id"
    InterfaceRegister ||--o{ InterfaceHazard : "interface_register_id"
    InterfaceHazard ||--o{ InterfaceControl : "interface_hazard_id"
    WorkPackage ||--o{ FieldAssuranceEvent : "work_package_id"
    FieldAssuranceEvent ||--o{ AssuranceFinding : "field_assurance_event_id"
    InterfaceControl ||--o{ AssuranceFinding : "interface_control_id"
    AssuranceFinding ||--o{ StopWorkEvent : "assurance_finding_id"
    AssuranceFinding ||--o{ CorrectiveAction : "assurance_finding_id"

Note the two edges from WorkPackage into InterfaceRegister: one for the package that owns the interface, one for the package it interacts with. That pair is what makes an overlap a queryable fact.

Contracts, Mobilisation and Demobilisation

erDiagram
    Organisation ||--o{ Contract : "contractor_organisation_id"
    Organisation ||--o{ Contract : "principal_organisation_id"
    Site ||--o{ Contract : "site_id"
    Contract ||--o{ Contract : "parent_contract_id"
    Contract ||--o{ ContractRequirement : "contract_id"
    WorkPackage ||--o{ SubcontractorEngagement : "work_package_id"
    Organisation ||--o{ SubcontractorEngagement : "subcontractor_organisation_id"
    WorkPackage ||--o{ Mobilisation : "work_package_id"
    Mobilisation ||--o{ MobilisationChecklistItem : "mobilisation_id"
    WorkPackage ||--o{ Demobilisation : "work_package_id"
    Contract ||--o{ ContractorPerformanceReview : "contract_id"
    ContractorPerformanceReview ||--o{ CorrectiveAction : "performance_review_id"

People, Access and Plant

Three independently-expiring records gate a person; plant is separated from its site approval.

erDiagram
    Organisation ||--o{ Person : "organisation_id"
    Person ||--o{ PersonCompetency : "person_id"
    Site ||--o{ SiteInduction : "site_id"
    Person ||--o{ SiteInduction : "person_id"
    Site ||--o{ SiteAccessAuthorisation : "site_id"
    Person ||--o{ SiteAccessAuthorisation : "person_id"
    WorkPackage ||--o{ SiteAccessAuthorisation : "work_package_id"
    Contract ||--o{ RoleRequirement : "contract_id"
    WorkPackage ||--o{ RoleRequirement : "work_package_id"
    Organisation ||--o{ ContractorPlant : "owning_organisation_id"
    ContractorPlant ||--o{ PlantSiteApproval : "contractor_plant_id"
    Site ||--o{ PlantSiteApproval : "site_id"
    ContractorPlant ||--o{ ContractorDocument : "plant_item_id"

Coordination, Incidents and Actions

erDiagram
    WorkPackage ||--o{ CoordinationMeeting : "work_package_id"
    CoordinationMeeting ||--o{ MeetingAttendance : "coordination_meeting_id"
    CoordinationMeeting ||--o{ InterfaceDecision : "coordination_meeting_id"
    InterfaceRegister ||--o{ InterfaceDecision : "interface_register_id"
    InterfaceDecision ||--o{ InterfaceDecision : "supersedes_decision_id"
    Site ||--o{ Incident : "site_id"
    WorkPackage ||--o{ Incident : "work_package_id"
    Incident ||--o{ CorrectiveAction : "incident_id"
    WorkPackage ||--o{ StopWorkEvent : "work_package_id"

Reading the Diagrams

  • A ||--o{ B means one row of A is referenced by many rows of B (the label is the foreign-key column on B).
  • These static diagrams show principal links only — the role columns present on nearly every model (*_person_id, *_organisation_id) are omitted for readability. The interactive viewer's Full ERD shows all 109, with the person/organisation noise toggleable.
  • Person has 42 of the 109 relationships because the model records who at every step: owns, approves, verifies, supervises, conducts, reviews, initiates, accepts handover. That accountability trail is the substance of contractor governance, not incidental metadata.
  • WorkPackage (14 links) is the structural hub — the viewer's Focus mode defaults to it.
  • One FK was dropped in translation to break a true 2-cycle: the proforma had Person.organisationId → Organisation and Organisation.primaryContactPersonId → Person. The Organisation side was dropped; a primary contact is recoverable by querying People in that organisation.

Diagrams are derived from the generated schema metadata (apps/csim/generated/json/csim_relationship_metadata.json). If the DSL schema changes, regenerate the metadata (python -m codegen.cli all csim) and update this page and the viewer's embedded data.