Layer 2 · flow

Issue flow

Maintenance and service requests, end to end.

Back to architecture

The issue flow handles every maintenance, service, or operational request raised in the building — by a resident, by staff, by a sensor, or by an automated check.

Submit. A resident describes a problem in the app, with optional photos, location, and unit context. Staff submit through the operations console with category and priority pre-filled. Sensor-driven submissions arrive from the IoT layer with structured payloads.

Categorize. The issue engine assigns a domain (Access, Deliveries, Spaces, Support, Lifecycle, Environment) and a severity tier. Categorization combines text classification, the building's domain taxonomy, and explicit overrides where staff intervention is appropriate.

Route. Each category resolves to one or more responders — on-site staff, contracted vendors, or automated subsystems. The routing engine attaches an SLA based on category and severity, and identifies escalation paths for missed SLAs.

Resolve. The responder works the issue with state visibility (acknowledged → in-progress → awaiting parts → resolved). Parts, vendor coordination, and elapsed time are tracked alongside the work order. Multi-step resolutions hand off cleanly between teams.

Close. Completion criteria are explicit per category. A closed issue includes the work performed, the time spent, and any parts consumed. Resident-facing closure messages fire through the notification engine with the building's tone.

Feedback. A short survey fires after closure — typically one or two questions calibrated to the issue type. The signal feeds Layer 6 in two places: the building's own scoring (trust index, friction minutes, promise-kept rate) and the cross-building intelligence corpus that informs the next version of the behavioral specification.

The flow is the same whether the issue is a broken bulb or a major HVAC failure. The difference shows up in the SLA, the routing, and the tone — not in the workflow shape.