Complaint Lifecycle

Eight States, and Exactly One Role Owns Each Transition

Section 3 of 4

A maintenance job is not a record with a status field — it is a negotiation between three parties that happens over hours or days, where money is agreed partway through and somebody physically travels to a property. The lifecycle below is the shape of that negotiation, and its defining property is that no state can be reached by the wrong party. A customer cannot mark work finished. An agent cannot accept their own quote on the tenant's behalf.

8

reachable states

3

roles driving transitions

7

distinct timestamps recorded

3

photo sets attached along the way

The State Machine

Each box names the state and the role permitted to write it. Colour indicates which party drives that transition — and the sequence deliberately alternates between them rather than letting any one role run the job end to end.

Pendingissue filed with photos, category and addresscustomerIn Pooltriaged into a trade category pool, left unassignedmanagerAcceptedclaimed by an agent in that category, assigned to themselvesagentQuoteSubmittedamount, note and site photos attachedagentAcceptedByCustomertenant approves the price they were showncustomerWorkStartedagent commits to the job and sets outagentPlaceReachedarrival at the property recordedagentWorkFinishedcompletion photos attached as evidenceagentManager may overridequote amount and noteResolved and Closed are modelled in the type but not yet reachable — the workflow currently ends at WorkFinishedcustomeragentmanager

How the Workflow Holds Together

Read the colour sequence and the design becomes visible: customer, manager, agent, agent, customer, agent, agent, agent. Control changes hands four times, and crucially it changes hands at every moment where a commitment is made.

The agent cannot proceed past quoting without the customer accepting the price. The customer cannot get work started without an agent choosing to take it. The manager decides what kind of job it is but cannot do the work or agree the price on the tenant's behalf. Each party is a checkpoint on the others, which is the actual product requirement — the software exists because these three parties do not fully trust each other to self-report.

The final run of agent-only states is the exception, and it is legitimate: once a price is agreed, starting, travelling and finishing are all things only the agent can observe. What keeps that stretch honest is not a permission but evidence, which is the next item.