Skip to content

Sub-Domain Blueprint: Unified Workflow

Domain: Unified (audit, communications, identity, library, notifications, search, signals, vault, workflow) Logical Sub-Domain: Workflow & Requests (Ops Engine) Physical Packages: @sd/mod-unified-workflow Related Documents: Data Definition Context: This document defines the Process Models, Routing Logic, and State Transitions for Operational Tasks. Status: Stable (v2.5)

1. Mandate

The Workflow Sub-Domain is the engine room of Operations. It is responsible for ingesting Service Requests (from Residents/Staff), Routing them to the correct Service Group (Maintenance, Security) based on a data-driven Catalog, and Escalating complex tasks into multi-step Work Orders.

2. Capabilities

Capability Description Component
Request Routing Automatically assigning submitted requests to Queues based on Catalog Rules. OperationsWorkflowService
Work Order Escalation Converting a simple Request into a managed Project with Line Items. WorkOrderService
Service Catalog Defining the "Menu" of available services, prices, and default providers. ServiceCatalogItem
Last Mile Delivery Automatically generating "Concierge Tasks" for physical item delivery. createLastMileTask
Procurement Signals Integration point for requesting purchase orders (PO) for parts/services. requestProcurement

3. Process Models

A. Request Submission & Routing

Happy Path for a Resident reporting a leak.

sequenceDiagram
    participant Resident
    participant Router as WorkflowService
    participant Mesh as ServiceMesh
    participant DB as Firestore (Requests)
    participant Maint as MaintenanceQueue

    Resident->>Router: submit(type="Leaking Pipe", unit="101")
    Router->>Mesh: getCatalogItem("Leaking Pipe")
    Mesh-->>Router: Item(Group="Maintenance", Priority="High")
    Router->>Router: applyRouting(Group="Maintenance")
    Router->>DB: save(status="submitted", assignedTo="Group:Maintenance")
    DB-->>Maint: Notify(New High Priority Request)

B. Work Order Escalation

Manager turns a request into a project with procurement.

sequenceDiagram
    participant Manager
    participant Service as WorkOrderService
    participant Signals as SignalBus
    participant Finance as FinanceModule

    Manager->>Service: escalateFromRequest(reqId)
    Service->>DB: createWorkOrder(parent=reqId, status="draft")
    Service->>DB: updateRequest(status="in_progress", link=woId)

    Manager->>Service: addLineItem("Replace Valve")
    Manager->>Service: requestProcurement(itemId, "Valve Part X")
    Service->>Signals: emit("PROCUREMENT_REQUEST", { item, amount })
    Signals-->>Finance: Listen & Process PO

4. State Machines

Service Request Lifecycle

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted: User Sends
    Submitted --> Triage: Auto-Routed
    Triage --> InProgress: Staff Ack
    InProgress --> PendingApproval: Budget Check
    InProgress --> Resolved: Work Done
    Resolved --> Closed: Customer Feedback / Timeout
    Resolved --> InProgress: Reopened

Work Order Lifecycle

stateDiagram-v2
    [*] --> Draft
    Draft --> Issued: Manager Approves
    Issued --> InProgress: Tech Starts
    InProgress --> OnHold: Waiting for Parts
    InProgress --> Completed: All Items Done
    Completed --> [*]

5. Interface Definitions

OperationsWorkflowService

  • handleSubmission(request, actorId): Promise<ServiceRequest>

WorkOrderService

  • escalateFromRequest(reqId, actorId): Promise<WorkOrder>
  • addLineItem(woId, data, actorId): Promise<WorkOrderItem>
  • requestProcurement(itemId, desc, actorId): Promise<poId>
  • completeWorkOrder(woId, actorId): Promise<void>

6. Changelog

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