Skip to content

Sub-Domain Blueprint: Operations Maintenance

Domain: Operations (maintenance, security, personnel, services) Logical Sub-Domain: Maintenance (Asset Care) Physical Packages: @sd/mod-operations/maintenance Related Documents: Data Definition Context: This document defines the Reactive Repair and Preventive Maintenance (PMP) cycles. Status: Stable (v2.5)

1. Mandate

The Maintenance Sub-Domain ensures physical asset integrity. It manages the full lifecycle of a Service Request (Ticket), whether it originates from a Resident (Reactive) or an Asset Heartbeat (Preventive). It integrates with Procurement to validate Vendor compliance before assignment.

2. Capabilities

Capability Description Component
Ticket Management Tracking repairs from Triage to Completion. ServiceRequest
Preventive Heartbeats Scheduling recurring inspections (PMP). AssetHeartbeat
Auto-Creation Converting HEARTBEAT_DUE signals into Inspection Tickets. handleSignal
Vendor Validation Preventing assignment to non-compliant vendors. assignRequest

3. Process Models

A. The Reactive Flow (Resident Report)

Happy Path: AC Failure.

sequenceDiagram
    participant Resident
    participant Service as MaintenanceService
    participant Vendor as Procurement
    participant DB as Firestore

    Resident->>Service: createRequest(title="AC Broken", unit="101")
    Service->>DB: create({ status: "triage", priority: "normal" })

    Note over Service: Manager Reviews

    Service->>Vendor: validate(vendorId)
    Vendor-->>Service: Active & Compliant
    Service->>DB: assignRequest(assignee=Vendor)

    Vendor->>Service: updateStatus("completed")
    Service->>SignalBus: emit("PROJECT_UPDATE", "Work Order Completed")

B. The Preventive Flow (Heartbeat)

Happy Path: Weekly Pump Inspection.

sequenceDiagram
    participant Cron
    participant Service as MaintenanceService
    participant Bus as SignalService

    Cron->>Service: processDueHeartbeats()
    Service->>DB: find(due <= NOW)

    loop Every Heartbeat
        Service->>Bus: emit("HEARTBEAT_DUE", { asset: "Pump A" })
        Service->>DB: update(nextDue = NOW + 7 days)
    end

    Bus->>Service: handleSignal("HEARTBEAT_DUE")
    Service->>DB: createRequest(title="Inspection: Pump A", type="maintenance")

4. State Machines

Service Request Status

stateDiagram-v2
    [*] --> Triage
    Triage --> Assigned: Staff/Vendor Selected
    Assigned --> InProgress: Work Started
    InProgress --> Blocked: Parts Needed
    InProgress --> Completed: Validated
    Completed --> [*]

5. Interface Definitions

MaintenanceService

  • createRequest(data): Promise<id>
  • assignRequest(id, admin, assignee): Promise<void>
  • processDueHeartbeats(): Promise<count>
  • scheduleCleaning(task): Promise<id>

6. Changelog

Date Author Description Reference
2026-01-24 Antigravity Initial creation Implementation Plan