A tenant reports a leaking sink. Someone reads the message, contacts a plumber, arranges access, and tells the owner what happened.
That sounds like a simple workflow—until the request lives in a text message, the approval sits in an email, and the invoice arrives in a different inbox.
For developers, the problem is familiar: scattered state, unclear ownership, and no reliable record of what happens next.
Property maintenance is a useful case study in designing software around real operational work. Here’s how we would approach the workflow as a system design exercise.
Start With an Explicit State Model
A single completed boolean cannot explain whether a request is waiting for approval, scheduled with a vendor, or still unassigned.
A more useful starting point is a small set of explicit states:
type MaintenanceStatus =
| "submitted"
| "triaged"
| "awaiting_approval"
| "ready_to_schedule"
| "scheduled"
| "in_progress"
| "awaiting_verification"
| "closed"
| "cancelled";
Each state should answer two questions:
What has happened?
Who needs to act next?
For example, awaiting_approval means the next action belongs to an authorized approver. awaiting_verification means reported completion still needs review.
The exact labels matter less than having consistent definitions and allowed transitions. Reopening a request should also be an explicit action with a reason.
Separate Urgency From Status
A request’s position in the workflow does not describe its urgency.
A broken cabinet handle and an active water leak might both be submitted. They should not enter the same operational queue with identical priority.
Model urgency separately:
interface MaintenanceRequest {
id: string;
propertyId: string;
unitId?: string;
status: MaintenanceStatus;
priority: "routine" | "urgent" | "emergency";
assignedTo?: string;
createdAt: string;
updatedAt: string;
}
A production system would also need attachments, access arrangements, approvals, and a history of changes.
Emergency handling needs a defined human escalation process. Saving a high-priority database record is not enough to ensure someone responds.
Make Approval Rules Enforceable
An approval threshold should influence what the system permits.
If an estimate exceeds the authorized amount, the workflow should require approval before ordinary scheduling proceeds. Any emergency exception needs its own documented authority and audit trail.
Enforce these rules on the server. Hiding a button in the interface does not prevent an unauthorized transition.
Approval should also apply to a specific estimate version. If the scope or price changes materially, an earlier approval should not silently authorize the new work.
Expect Duplicate Messages and Failed Notifications
Real workflows include retries.
A tenant taps submit twice. A vendor resends a completion update. A notification service times out after accepting a message.
Use idempotency keys where repeated operations could create duplicate requests or actions. Record notification delivery separately from the request’s operational status.
“Email sent” and “repair scheduled” are different facts. One should never stand in for the other.
Keep a History Without Building an Entire Event-Sourcing Platform
A current-status field is useful for displaying the queue. An append-only activity history explains how the request reached that state.
Record the actor, timestamp, action, and relevant change. Update the current state and its history entry in one transaction so they stay consistent.
Access matters, too. Tenants should see their own requests. Vendors should receive only the information needed for assigned work. Owners should have visibility into properties they are authorized to access.
Measure the Handoffs
A dashboard showing “12 open tickets” gives limited operational insight.
More useful questions include:
Which requests have no assigned owner?
How long have requests waited for approval?
Which scheduled jobs are overdue?
Which completed repairs still need verification?
These views help people identify the next action.
The design principle is straightforward: make responsibility visible, preserve the history, and distinguish a recorded update from a completed outcome.
That applies to property maintenance—and to almost any software coordinating work between people.
Winvest Management provides rental property management services in the Miami area. This article presents a conceptual software design, not a description of the company’s internal technology. Learn more at winvestmanagement.com.
Top comments (0)