Application Overview

What the Solar Farm Maintenance Operations Hub models, and the ideas behind it

Core Operating Chain

Organisation → Person                                (parties and the people in them)
Portfolio → SolarFarm                                (what is owned, and where)
  SolarFarm → SiteZone (self-nesting) → AssetLocation
  SolarFarm / AssetType / AssetLocation → Asset (self-nesting)   THE EQUIPMENT

DETECTION
  SourceSystem / SolarFarm / Asset → AlarmEventReference   (a governed alarm reference)
  AlarmEventReference / Inspection → ServiceRequest        (a request for action)
  ServiceRequest / DefectCategory / Asset → Defect         (what is actually wrong)
    Defect → OperationalImpact                     (lost or derated capacity)
    Defect → PriorityAssessment                    (how fast to respond — P1…P5)

RESPONSE
  Defect / MaintenanceTemplate → WorkOrder         (the planned job)
    WorkOrder → WorkTask                           (the steps)
    WorkOrder → WorkAssignment                     (who does it, from which org)
    WorkOrder → WorkDependency / WorkStatusHistory (what gates it, and the trail)

MAKE SAFE
  WorkOrder → IsolationReference                   (requested · applied · proved dead · restored)
  WorkOrder → AccessRequirement
  WorkOrder → SafetyDocument ← Document            (SWMS/JSEA accepted before work)

FIELD RECORD
  WorkOrder / Asset / Inspection → Measurement     (voltage, IR, output, grass height…)
  WorkOrder / Defect / Inspection → Evidence       (photo, thermal, test result)
  WorkOrder → TechnicianNote / TestResult
  WorkOrder → PartRequirement / PartUsage / RemovedComponent
    RemovedComponent → WarrantyClaim               (recovery from the manufacturer)

THREE SEPARATE ACTS OF CLOSURE
  WorkOrder / Asset → ReturnToService              (equipment safely re-energised)
    Defect / WorkOrder / ReturnToService → Verification   (independently confirmed)
      Defect / WorkOrder → Closeout                (defect formally closed)

SPECIALIST STREAMS
  SolarFarm / SiteZone → VegetationZone → VegetationInspection
  SolarFarm / SourceSystem → WeatherEvent

Key Concepts

A closed defect is traceable back to the alarm that raised it. The spine of the model is one long chain, and the demo carries it end to end for a single inverter fault. SCADA alarm SCADA-2026-0724-1142 (DC input imbalance on INV-07A) raises service request SR-000142, which becomes defect DEF-000381; priority assessment scores it P2_URGENT; work order WO-000529 is planned, assigned and worked; a DC isolation is applied and proved dead; measurements, tests and photo evidence are captured; the failed board is removed and a new one installed; the inverter is returned to service; a reliability engineer verifies the fix by 48-hour output monitoring; and the closeout records 450 kW restored as a first-time fix. You can read that chain in either direction from any point.

Three acts of closure, never conflated. This is the pack's central design principle, and the schema enforces it structurally by making them three separate models. ReturnToService records that the equipment is safely re-energised — isolation restored, protection normal, alarms cleared, output confirmed. Verification records that someone independent (in the demo, a different person from the technician) has confirmed the defect is genuinely resolved. Closeout records that the operational defect is formally closed, with failure mode, root cause, capacity restored and whether it was a first-time fix. A technician downing tools is not the same as the plant being safe, and neither is the same as the problem being demonstrably gone.

A defect is not closed because someone says so. In the demo the defect moves to CLOSED only after a Verification with result ACCEPTED exists behind it, and the closeout is separately client_accepted by the asset owner. The work-order status history walks DRAFT → PLANNED → ASSIGNED → IN_PROGRESS → RETURNED_TO_SERVICE → READY_FOR_VERIFICATION → CLOSED, so the order of events is legible from the records themselves.

Isolation is a proved state, not a checkbox. IsolationReference carries the full sequence a real permit-to-work follows: REQUESTED → APPROVED → APPLIED → PROVED_DEAD → RELEASED_FOR_WORK → … → RESTORED, with timestamps for each transition, a lock/tag reference and an earthing flag. In the demo the DC isolation on INV-07A is proved dead at 07:10 and work is not released until 07:15 — the isolation gate on the work order is a real WorkDependency row that is SATISFIED before the job starts.

Accountability is separable by design. Wherever a decision needs a second person, the schema gives it its own column, and tab_config.yaml labels every role so a Person page reads them as distinct facts: a priority is assessed_by and approved_by; an isolation is requested_by and authorised; an inspection has an inspector and a reviewed_by; a return to service separates requested_by from returned_by; a closeout separates closed_by from client_accepted_by. On an Asset page, "Measurements Of" and "Measurements Taken With" are two different tabs because an asset can be the thing measured or the instrument.

Warranty recovery is tied to the physical part. A Defect flagged warranty_candidate drives a WarrantyClaim that references the exact RemovedComponent (with its serial number and disposition of WARRANTY_RETURN), the work order, the asset and the manufacturer organisation. The demo's failed DC input monitoring board DIM440-2022-0417 is booked out, sent for manufacturer analysis, and claim CLAIM-000078 is SUBMITTED for $1,850.

Vegetation is a first-class maintenance stream. VegetationZone carries a target_height_mm, an intervention_height_mm and a firebreak_required flag; a VegetationInspection measures actual heights and grades the result. In the demo zone VZ07 reads 340 mm against a 300 mm intervention threshold, which raises a fire-risk vegetation defect and a preventive vegetation work order — the same defect → work-order machinery as the electrical fault, but a different discipline.

References are stored, live feeds are not. The boundary carried over from the pack: live high-frequency SCADA and weather telemetry stay in specialist systems. What is stored here is the governed reference — AlarmEventReference holds the external event id, code, severity, a summary and a link back to the raw event; SourceSystem names where it came from; external_cmms_reference, external_reference and raw_reference_url carry the handles. The hub stores decisions, measurements, evidence and outcomes — not the historian.

What Is Phase 2

The proforma pack ships workflows.yaml (defect, work-order and warranty state machines), business_rules.yaml (validation, workflow guards and escalation), dashboards.yaml, views.yaml (operational queues), mobile_forms.yaml and permissions.yaml, plus reference-numbering masks (SR-######, DEF-######, WO-######, CLAIM-######). 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. Estimated-vs-actual hours and costs are stored values the seed sets, not roll-ups. The mobile field forms and offline capture policy are documented intent, not built.

See the header of apps/solarfarm/schema/solarfarm.dsl for the full translation record. In summary: the pack's 51 models became 50 (the AuditRecord model was dropped — the framework provides audit history); created_at / updated_at columns were dropped throughout; Decimal became Float and Date became DateTime; the controlled-value comments became inline [enum: …] lists; tables were reordered so every foreign key points backward (no true reference cycle existed, so none had to be broken); and four short name columns were added (Person, Defect, ServiceRequest, Evidence) so list views show a readable label instead of a whole description paragraph.