Application Overview

What the Geotechnical and Ground-Control Management app models, and the ideas behind it

Core Operating Chain

Site → Area → Excavation                       (where the ground is)
  Excavation ↔ GeotechnicalDomain              (ExcavationDomain — what the ground is)
  Site → GroundControlPlan (self-superseding)  (how it is governed)
  Site/Excavation → DesignBasis                (assumptions, criteria, acceptance)

GeotechnicalHazard → HazardControl             (what can go wrong + what stops it)

InspectionTemplate → InspectionItem
Inspection → InspectionResponse                (what was checked, item by item)
Inspection → GroundObservation                 (what the field actually saw)

GroundSupportDesign → GroundSupportInstallation → SupportInspection

MonitoringInstrument → InstrumentChannel → MonitoringReading
                        InstrumentChannel → MonitoringCurrent   (one live row per channel)
ThresholdSet → ThresholdRule  (evaluated against a channel)

           ┌─ reading breaches a rule for its persistence ─┐
TarpPlan → TarpAction                                       ▼
TarpActivation → TarpActionExecution           (the plan's actions, executed + verified)
TarpActivation → OperationalRestriction        (who is kept out, and the release criteria)

GroundObservation / TarpActivation / GeotechnicalEvent → WorkRequest → WorkVerification
TarpActivation / Hazard / Event → TechnicalReview → CorrectiveAction
DesignBasis / TarpPlan → ManagementOfChange    (the loop closes on the design)

EvidenceAttachment  (polymorphic — photos, surveys, exports on any record)

Key Concepts

A restriction is traceable to the evidence that justified it. The spine of the model is the trigger chain: a MonitoringReading on an InstrumentChannel breaches a ThresholdRule for its persistence_seconds; that creates a TarpActivation which records triggered_by_reading_id, triggering_threshold_reference (the versioned set, not just the number), and often a triggered_by_observation_id as well; the activation imposes an OperationalRestriction whose release_criteria is a required text field. The demo carries the full arc — radar reading 2.4 mm/h → activation GEO-TARP-2026-00003 → the ramp exclusion GEO-RES-2026-00003 — so you can read forward from a number to an exclusion zone and back again.

A TARP does not de-escalate itself. This is the load-bearing rule the proforma pack repeats (NoAutomaticTarpDeescalation, SuspectReadingCannotDeescalate). In the demo the radar movement rate returns to 0.5 mm/h by 22 July, but the activation's current_level stays at LEVEL_2 and its deescalated_at / closed_at remain null until the recorded competent-person decision — de-escalation is a decision, not an automatic consequence of a quiet reading. A SUSPECT piezometer reading is present precisely to show that suspect quality can never lower a level.

Readings are governed metadata, not the sensor feed. The boundary carried over from the pack: raw radar, seismic, survey and high-frequency instrument data stays in the specialist source platform. MonitoringInstrument and MonitoringReading carry source_system / source_identifier / source_reference handles and a quality classification (VALID · ESTIMATED · SUSPECT · REJECTED · MISSING); MonitoringCurrent holds one live row per channel with a current_tarp_level, trend_direction and rate_of_change. What is stored here is the validated reading or summary, the decision and the evidence — not the historian.

Immutability is by supersession, not editing. Approved plans, designs and readings are corrected by writing a superseding record with a recorded reason, not by editing the original (ImmutableApprovedEvidence). The demo shows this directly: GroundControlPlan Rev A is SUPERSEDED and Rev B is ACTIVE, with Rev B's supersedes_plan_id pointing back at Rev A; the 2024 DesignBasis GEO-DES-00013 sits SUPERSEDED alongside the current GEO-DES-00014.

Accountability is separable by design. Wherever a decision needs a second person, the schema gives it its own column: OperationalRestriction carries both authorised_by_person_id and release_approved_by_person_id; WorkRequest → WorkVerification.verified_by_person_id is a different person from the requester; CorrectiveAction separates owner_person_id from verified_by_person_id; ManagementOfChange carries distinct technical and operational approvers. The tab_config.yaml labels every one of these roles so a Person page reads "Restrictions Authorised" and "Restriction Releases Approved" as different facts.

Completed work does not close the hazard. WorkCompletionRequiresVerification and RestrictionReleaseControl from the pack: a VERIFIED work request with a passing WorkVerification only recommends release (restriction_release_recommended) — the restriction still needs its criteria satisfied and an authorised release approval before status moves to RELEASED. The demo's restriction is deliberately left ACTIVE with the work already verified, so the "verified but not yet released" state is visible.

The application is not the response. The boundary worth repeating: competent geotechnical judgement remains authoritative, and live emergency response must remain usable without this application or the network. What is modelled here is the preparation, monitoring, decision record and improvement around ground control — hazards, readings, thresholds, activations, restrictions and evidence — not the real-time command of a slope failure.

What Is Phase 2

The proforma pack ships six workflows (routine_inspection, post_event_reentry, monitoring_threshold_response, ground_support_installation, geotechnical_event_response, design_change) and sixteen business rules (active_excavation_requires_current_design, high_observation_immediate_control, tarp_no_automatic_deescalation, restriction_release_verified, immutable_approved_evidence, …), plus the numbering masks (GEO-INSP-{YYYY}-{SEQ:06} and friends), the five dashboards, four reports and the mobile field flows. None of that is enforced by the schema — the demo data is consistent with those rules rather than validated against them, and the reference numbers follow the masks by hand. The graph projections and analytics datasets in ggcm_application.yaml are likewise documented intent, not built. See the header of apps/ggcm/schema/ggcm.dsl for the full translation record, including the one enum that had to be repaired (ReviewType, whose whitespace-tokenised values would have produced four duplicate REVIEW entries).