System Diagram

The Geotechnical and Ground-Control Management data model, mapped — 38 models, 131 relationships

🔍 For serious exploration, open the Interactive Diagram Viewer — pan, mouse-wheel zoom, fit-to-screen, full-screen, per-module tabs, the full 131-relationship ERD, and a focus mode that draws one model and its neighbours at a chosen depth. Person (36 links), Site (21) and Area (13) are role/location 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

Ten 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 SPATIAL["⛰️ Sites & excavations"]
        Site --> Area --> Excavation
        Site --> GeotechnicalDomain
        Excavation --> ExcavationDomain
        GeotechnicalDomain --> ExcavationDomain
    end

    subgraph DESIGN["📐 Plans & design"]
        GroundControlPlan
        DesignBasis
    end

    subgraph HAZ["⚠️ Hazards & controls"]
        GeotechnicalHazard --> HazardControl
    end

    subgraph INSP["🔦 Inspections"]
        InspectionTemplate --> InspectionItem
        Inspection --> InspectionResponse
        Inspection --> GroundObservation
    end

    subgraph SUP["🔩 Ground support"]
        GroundSupportDesign --> GroundSupportInstallation --> SupportInspection
    end

    subgraph MON["📡 Monitoring & thresholds"]
        MonitoringInstrument --> InstrumentChannel
        InstrumentChannel --> MonitoringReading
        InstrumentChannel --> MonitoringCurrent
        ThresholdSet --> ThresholdRule
    end

    subgraph TARP["🚨 TARP & restrictions"]
        TarpPlan --> TarpAction
        TarpActivation --> TarpActionExecution
        TarpActivation --> OperationalRestriction
    end

    subgraph EVT["🧭 Events, work & review"]
        GeotechnicalEvent
        WorkRequest --> WorkVerification
        TechnicalReview --> CorrectiveAction
        ManagementOfChange
    end

    Excavation --> GeotechnicalHazard
    Excavation --> DesignBasis
    Excavation --> GroundSupportDesign
    Excavation --> MonitoringInstrument
    GeotechnicalHazard --> GroundObservation
    InstrumentChannel --> ThresholdRule
    MonitoringReading --> TarpActivation
    GroundObservation --> TarpActivation
    GeotechnicalEvent --> TarpActivation
    TarpPlan --> TarpActivation
    GroundObservation --> WorkRequest
    TarpActivation --> WorkRequest
    TarpActivation --> TechnicalReview
    TarpActivation --> OperationalRestriction
    DesignBasis --> ManagementOfChange
    TarpPlan --> ManagementOfChange

(The TarpActivation node is the hub of the domain — it points backward at its trigger (MonitoringReading / GroundObservation / GeotechnicalEvent) and its plan, and forward at the executions, restriction, work, review and change it sets in motion. Fifteen relationships touch it.)

Sites, Areas, Excavations and Domains

The spatial spine. Areas, geotechnical domains and excavations each self-nest, and an excavation intersects one or more domains through the ExcavationDomain join.

erDiagram
    Organisation ||--o{ Site : "operator_organisation_id"
    Site ||--o{ Area : "site_id"
    Area ||--o{ Area : "parent_area_id"
    Site ||--o{ GeotechnicalDomain : "site_id"
    GeotechnicalDomain ||--o{ GeotechnicalDomain : "parent_domain_id"
    Site ||--o{ Excavation : "site_id"
    Area ||--o{ Excavation : "area_id"
    Excavation ||--o{ Excavation : "parent_excavation_id"
    Excavation ||--o{ ExcavationDomain : "excavation_id"
    GeotechnicalDomain ||--o{ ExcavationDomain : "geotechnical_domain_id"

Plans, Design Basis and Hazards

How ground is governed, and what can go wrong. A ground-control plan revision supersedes the previous one rather than overwriting it; hazards carry their critical controls.

erDiagram
    Site ||--o{ GroundControlPlan : "site_id"
    GroundControlPlan ||--o{ GroundControlPlan : "supersedes_plan_id"
    Document ||--o{ GroundControlPlan : "document_id"
    Site ||--o{ DesignBasis : "site_id"
    Excavation ||--o{ DesignBasis : "excavation_id"
    Site ||--o{ GeotechnicalHazard : "site_id"
    Excavation ||--o{ GeotechnicalHazard : "excavation_id"
    GeotechnicalDomain ||--o{ GeotechnicalHazard : "geotechnical_domain_id"
    GeotechnicalHazard ||--o{ HazardControl : "geotechnical_hazard_id"

Inspections and Observations

Templates define what is checked; inspections record it item by item and raise the observations that drive the response.

erDiagram
    Site ||--o{ InspectionTemplate : "site_id"
    InspectionTemplate ||--o{ InspectionItem : "inspection_template_id"
    Site ||--o{ Inspection : "site_id"
    Excavation ||--o{ Inspection : "excavation_id"
    InspectionTemplate ||--o{ Inspection : "inspection_template_id"
    Inspection ||--o{ InspectionResponse : "inspection_id"
    InspectionItem ||--o{ InspectionResponse : "inspection_item_id"
    Inspection ||--o{ GroundObservation : "inspection_id"
    GeotechnicalHazard ||--o{ GroundObservation : "geotechnical_hazard_id"

Ground Support

Design → what was actually installed → the condition inspections that follow.

erDiagram
    Excavation ||--o{ GroundSupportDesign : "excavation_id"
    DesignBasis ||--o{ GroundSupportDesign : "design_basis_id"
    Excavation ||--o{ GroundSupportInstallation : "excavation_id"
    GroundSupportDesign ||--o{ GroundSupportInstallation : "ground_support_design_id"
    Organisation ||--o{ GroundSupportInstallation : "installed_by_organisation_id"
    GroundSupportInstallation ||--o{ SupportInspection : "ground_support_installation_id"
    Inspection ||--o{ SupportInspection : "inspection_id"

Monitoring and Thresholds

The measurement backbone. Instruments carry channels; channels carry a time-ordered MonitoringReading history and one live MonitoringCurrent row; threshold rules are evaluated against a channel.

erDiagram
    Site ||--o{ MonitoringInstrument : "site_id"
    Excavation ||--o{ MonitoringInstrument : "excavation_id"
    GeotechnicalDomain ||--o{ MonitoringInstrument : "geotechnical_domain_id"
    MonitoringInstrument ||--o{ InstrumentChannel : "monitoring_instrument_id"
    InstrumentChannel ||--o{ MonitoringReading : "instrument_channel_id"
    InstrumentChannel ||--o{ MonitoringCurrent : "instrument_channel_id"
    Site ||--o{ ThresholdSet : "site_id"
    ThresholdSet ||--o{ ThresholdRule : "threshold_set_id"
    InstrumentChannel ||--o{ ThresholdRule : "instrument_channel_id"

The TARP Spine

Everything about an activation hangs off TarpActivation — it records what triggered it (a reading, an observation or an event), instantiates the plan's actions as executions, and imposes the restriction.

erDiagram
    Site ||--o{ TarpPlan : "site_id"
    TarpPlan ||--o{ TarpAction : "tarp_plan_id"
    TarpPlan ||--o{ TarpActivation : "tarp_plan_id"
    MonitoringReading ||--o{ TarpActivation : "triggered_by_reading_id"
    GroundObservation ||--o{ TarpActivation : "triggered_by_observation_id"
    GeotechnicalEvent ||--o{ TarpActivation : "triggered_by_event_id"
    GeotechnicalHazard ||--o{ TarpActivation : "geotechnical_hazard_id"
    TarpActivation ||--o{ TarpActionExecution : "tarp_activation_id"
    TarpAction ||--o{ TarpActionExecution : "tarp_action_id"
    TarpActivation ||--o{ OperationalRestriction : "tarp_activation_id"
    GeotechnicalEvent ||--o{ OperationalRestriction : "geotechnical_event_id"

Events, Work, Review and Change

The improvement loop. Work is requested from an observation, an activation or an event, and independently verified; reviews raise corrective actions; design and TARP changes go through management of change.

erDiagram
    GroundObservation ||--o{ WorkRequest : "ground_observation_id"
    TarpActivation ||--o{ WorkRequest : "tarp_activation_id"
    GeotechnicalEvent ||--o{ WorkRequest : "geotechnical_event_id"
    WorkRequest ||--o{ WorkVerification : "work_request_id"
    GeotechnicalHazard ||--o{ TechnicalReview : "geotechnical_hazard_id"
    TarpActivation ||--o{ TechnicalReview : "tarp_activation_id"
    GeotechnicalEvent ||--o{ TechnicalReview : "geotechnical_event_id"
    TechnicalReview ||--o{ CorrectiveAction : "technical_review_id"
    GeotechnicalEvent ||--o{ CorrectiveAction : "geotechnical_event_id"
    DesignBasis ||--o{ ManagementOfChange : "affected_design_basis_id"
    TarpPlan ||--o{ ManagementOfChange : "affected_tarp_plan_id"

Application Flow — Inspection to Release

The order in which the system is actually used, and what gates each step.

flowchart TD
    A["🌧️ Rainfall / blast / seismic trigger"] --> B["🔦 Post-event re-entry inspection<br/><i>access restricted pending result</i>"]
    B --> C{"Safe for access?<br/><i>severity, cracks, seepage</i>"}
    C -->|no| D["🚩 Ground observation raised<br/><i>HIGH / CRITICAL</i>"]
    C -->|yes| E["✅ Re-entry authorised"]
    A2["📡 Channel reading imported<br/><i>VALID / SUSPECT quality</i>"] --> F{"Threshold rule met<br/>for its persistence?"}
    F -->|"SUSPECT / REJECTED"| G["⚠️ Flagged — but cannot<br/>lower any TARP level"]
    F -->|"VALID, breached"| H["🚨 TARP activation<br/><i>preserves reading + threshold version</i>"]
    D --> H
    H --> I["▶️ Instantiate level actions<br/>as TarpActionExecution"]
    I --> J["⛔ Operational restriction<br/><i>release criteria required</i>"]
    J --> K["🔧 Work request<br/><i>scale · drain · reprofile · support</i>"]
    K --> L{"Work verified by<br/>someone other than requester?"}
    L -->|no| K
    L -->|yes| M["🧭 Technical review<br/><i>trend, rainfall, groundwater</i>"]
    M --> N{"Release criteria satisfied<br/>AND competent-person approval?"}
    N -->|no| O["Restriction stays ACTIVE<br/>TARP stays at level"]
    O --> M
    N -->|yes| P["🔓 Restriction RELEASED<br/>TARP de-escalation approved"]
    M --> Q["📐 Management of change<br/><i>if design / threshold changes</i>"]
    Q --> A2

Application Flow — Why a Quiet Reading Doesn't De-escalate

The single most important rule in the domain, drawn out.

flowchart TD
    S(["TARP at LEVEL_2"]) --> R["📉 Later reading returns<br/>below threshold"]
    R --> Q{"Does the level drop<br/>automatically?"}
    Q -->|"NO — by design"| K1["Retain the active activation"]
    K1 --> K2["Complete the level-specific<br/>TarpActionExecution records"]
    K2 --> K3["🧭 Competent-person review<br/><i>trend genuine? drainage fixed?</i>"]
    K3 --> K4{"Explicit de-escalation<br/>approval recorded?"}
    K4 -->|no| K3
    K4 -->|yes| K5["✅ current_level lowered<br/>deescalated_at + approver stamped"]
    R -.->|"if reading is SUSPECT/REJECTED"| X["❌ Cannot even be considered<br/>for de-escalation"]

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, area_id) are omitted for readability. The interactive viewer's Full ERD shows all 131, with the person/site/area noise toggleable.
  • TarpActivation is the hub of the domain — the viewer's Focus mode defaults to it, with 15 links. Person has the most (36) because every ground-control act records who did it: owned, responsible, prepared, reviewed, approved, inspected, observed, activated, authorised, verified, requested, released.
  • No FK was dropped in translation — the proforma graph was acyclic, so every relationship in the source model is present. Document was hoisted above the plan/design/TARP models that reference it, and GeotechnicalEvent above TarpActivation (which carries triggered_by_event_id). Area.parent_area_id, GeotechnicalDomain.parent_domain_id, Excavation.parent_excavation_id and GroundControlPlan.supersedes_plan_id are self-references.
  • One pointer is deliberately not a foreign key: EvidenceAttachment.entity_type + entity_id is a polymorphic reference — an attachment can hang off an observation, an activation, a restriction, a work request or a review — so it is a type/id pair, not an edge.

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