System Diagram

The Isolation & Permit to Work data model, mapped — 35 models, 114 relationships

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

Architecture Overview

Eight 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 PLANT["⚙️ Plant & energy"]
        Site --> Area --> Asset
        Asset --> EnergySource --> IsolationPoint
        ControlledDocument
    end

    subgraph TMPL["📋 Isolation templates"]
        IsolationTemplate --> IsolationTemplateStep
    end

    subgraph ISO["🔒 Isolation"]
        IsolationRequest --> IsolationStep --> IsolationVerification
        IsolationRequest --> IsolationAsset
        IsolationRequest --> TestRelease
        IsolationRequest --> RestorationChecklist
    end

    subgraph LOCKS["🔑 Locks, tags & group boards"]
        Lock --> LockApplication
        Tag --> LockApplication
        GroupIsolationBoard --> BoardParticipant
    end

    subgraph PTW["📝 Permits & work"]
        Permit --> PermitControl
        Permit --> PermitWorker
        Permit --> WorkExecution
        Permit --> PermitHandover
        WorkRequest
    end

    subgraph ASSUR["⚠️ Events & assurance"]
        IsolationEvent --> CorrectiveAction
        Audit --> AuditFinding --> CorrectiveAction
        Approval
    end

    Asset --> IsolationTemplate
    IsolationPoint --> IsolationTemplateStep
    IsolationTemplate --> IsolationRequest
    WorkRequest --> IsolationRequest
    IsolationPoint --> IsolationStep
    IsolationRequest --> LockApplication
    IsolationRequest --> GroupIsolationBoard
    IsolationRequest --> Permit
    WorkRequest --> Permit
    IsolationRequest --> IsolationEvent
    Approval --> LockApplication

Plant, Energy and Isolation Points

The hazard inventory. Every isolation point traces back to a specific energy source on a specific asset.

erDiagram
    Organisation ||--o{ Site : "organisation_id"
    Site ||--o{ Area : "site_id"
    Area ||--o{ Area : "parent_area_id"
    Site ||--o{ Asset : "site_id"
    Area ||--o{ Asset : "area_id"
    Asset ||--o{ Asset : "parent_asset_id"
    Asset ||--o{ EnergySource : "asset_id"
    Asset ||--o{ EnergySource : "source_asset_id"
    EnergySource ||--o{ IsolationPoint : "energy_source_id"
    Asset ||--o{ IsolationPoint : "asset_id"
    Site ||--o{ ControlledDocument : "site_id"

The Isolation Spine

Template → request → step → verification, with locks and the group board.

erDiagram
    Asset ||--o{ IsolationTemplate : "asset_id"
    ControlledDocument ||--o{ IsolationTemplate : "controlled_document_id"
    IsolationTemplate ||--o{ IsolationTemplateStep : "isolation_template_id"
    IsolationPoint ||--o{ IsolationTemplateStep : "isolation_point_id"
    WorkRequest ||--o{ IsolationRequest : "work_request_id"
    IsolationTemplate ||--o{ IsolationRequest : "isolation_template_id"
    IsolationRequest ||--o{ IsolationAsset : "isolation_request_id"
    IsolationRequest ||--o{ IsolationStep : "isolation_request_id"
    IsolationPoint ||--o{ IsolationStep : "isolation_point_id"
    IsolationRequest ||--o{ IsolationVerification : "isolation_request_id"
    IsolationStep ||--o{ IsolationVerification : "isolation_step_id"
    IsolationRequest ||--o{ LockApplication : "isolation_request_id"
    IsolationStep ||--o{ LockApplication : "isolation_step_id"
    Lock ||--o{ LockApplication : "lock_id"
    Tag ||--o{ LockApplication : "tag_id"
    Approval ||--o{ LockApplication : "forced_removal_approval_id"
    IsolationRequest ||--o{ GroupIsolationBoard : "isolation_request_id"
    Lock ||--o{ GroupIsolationBoard : "master_lock_id"
    GroupIsolationBoard ||--o{ BoardParticipant : "group_isolation_board_id"
    Lock ||--o{ BoardParticipant : "personal_lock_id"

Permits, Work, Testing and Restoration

erDiagram
    IsolationRequest ||--o{ Permit : "isolation_request_id"
    WorkRequest ||--o{ Permit : "work_request_id"
    Permit ||--o{ PermitControl : "permit_id"
    Permit ||--o{ PermitWorker : "permit_id"
    Permit ||--o{ WorkExecution : "permit_id"
    WorkRequest ||--o{ WorkExecution : "work_request_id"
    Permit ||--o{ PermitHandover : "permit_id"
    IsolationRequest ||--o{ TestRelease : "isolation_request_id"
    Permit ||--o{ TestRelease : "permit_id"
    IsolationRequest ||--o{ RestorationChecklist : "isolation_request_id"

Events, Audit and Corrective Action

erDiagram
    IsolationRequest ||--o{ IsolationEvent : "isolation_request_id"
    Permit ||--o{ IsolationEvent : "permit_id"
    IsolationEvent ||--o{ CorrectiveAction : "isolation_event_id"
    Audit ||--o{ AuditFinding : "audit_id"
    AuditFinding ||--o{ CorrectiveAction : "audit_finding_id"
    Person ||--o{ Authorisation : "person_id"
    Attachment ||--o{ CorrectiveAction : "evidence_attachment_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 that appear on nearly every model (*_person_id, site_id, *_attachment_id) are omitted for readability. The interactive viewer's Full ERD shows all 114, with the person/site/attachment noise toggleable.
  • IsolationRequest is the hub of the domain — the viewer's Focus mode defaults to it. Person has the most links (44) because every safety action records who did it: applied, dissipated, verified, independently verified, restored, checked, issued, accepted, approved.
  • No FK was dropped in translation — unlike some proforma packs, this graph was acyclic, so every relationship in the source model is present.
  • Polymorphic pointers (Approval, Attachment and Notification each reference many different target tables) are modelled as entity_type + entity_key string pairs rather than real foreign keys, so they do not appear as edges.

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