Requirements, for approval
Plumber Assistant
A booking assistant for a plumbing firm: what it does, what it does not do, and what it costs to build. Written before the work started, and kept so the finished thing can be checked against it.
Abad Naseer · 11 August 2026 · a separate system, sharing only the engineering
Requirements, for approval.
A booking assistant for a plumbing firm. A customer describes a problem in their own words, the assistant works out which service that is, and they book a time in Calendly. There is no basket and no checkout, because a visit is one job at one time rather than a list of things.
It is a separate system. Its own application, its own database, its own address, its own office screens. Nothing is shared with the grocery assistant while either is running, so neither can affect the other, and the two can be sold, priced and supported apart.
What it inherits is the engineering. The parts that took longest to get right, understanding what somebody said and matching it against a list in milliseconds, are already built and running. That is why a system of this size is measured in weeks rather than months.
| Who it is for | One plumbing firm and its customers |
| How a time is booked | Calendly, which the firm already keeps |
| Shares with the grocery system | Nothing at run time |
| New paid service | A Calendly plan that includes webhooks |
| Genuinely new engineering | The booking step |
Out of scope, so that it is written down: there is no directory of plumbers, no way for a plumber to sign themselves up, and no bidding between firms. This is one firm's own assistant.
This is the whole of the difference. Everything either side of it, understanding what was asked for and confirming what was agreed, already works in the grocery system.
The assistant asks at most one question back. Where it cannot place the job with confidence it says so and offers a callback, rather than booking the wrong visit and losing a morning.
The conversation is saved against the job, so the plumber arrives knowing what the customer actually said.
Seven tables, designed for jobs. A job has an address, a duration, a technician and a history of being moved, and none of those belong on a shopping order, which is why this is a new schema rather than a renamed one.
| Table | Holds |
|---|---|
services | Name, description, price range, expected duration, whether it is an emergency call |
jobs | The booking: customer, service, address, status, and the conversation |
job_lines | Service, parts and labour, so a job can be priced afterwards |
appointments | Start, end, technician, calendar reference, status |
technicians | Who can take which service, and their working hours |
service_areas | Postcodes covered, and any travel surcharge |
customers | Contact details and the address, kept between visits |
Only appointments is load bearing on day one. technicians and service_areas can hold a single row each until the firm needs more.
One new subscription and one new piece of engineering. Everything else on that diagram has been running in production for months.
The matching engine is the one already searching 25,631 grocery products in milliseconds. A plumbing firm has tens of services, so the engine has an easier job here than it does today.
The work is the vocabulary rather than the technology. A customer says "my boiler is making a banging noise". They do not say "central heating diagnostic". Collecting the first kind of phrase, with the firm, is the main content task in this build.
The firm keeps working in Calendly, which they already use. Nothing about how they run their diary has to change.
Two things need care, and both are on that diagram. A slot has to be held while the customer decides, or two people book the same hour. And when the plumber moves a job in their own calendar, the system has to hear about it, or the office rings a customer about a visit that changed hours ago.
Same shape as the grocery assistant, which is already built and tested.
| Screen | Does |
|---|---|
| Chat | Describe the problem, by typing or speaking |
| Booking panel | Available times for the matched service, in place of a basket |
| Confirmation | What was booked, when, and what it is expected to cost |
| Office | The day ahead, today's jobs, and one place to see a customer's history |
| Endpoint | Does |
|---|---|
POST /chat | A turn of conversation |
POST /voice | A spoken turn |
GET /services | The service list |
GET /availability | Free slots for a service |
POST /bookings | Take a slot and create the job |
POST /webhooks/calendly | Told when a booking moves or is cancelled |
GET /admin/jobs | The day, for the office |
Phases one and two produce something the firm can use, with bookings taken by phone. Phase three is where the new engineering sits, and it is the phase to protect from being squeezed.
Phase four is optional. Card payments, cash and PayPal were built for the grocery system and the design carries straight over if the firm wants deposits.
These four answers change the build, so they are worth settling before phase three starts.
| Question | Why it matters |
|---|---|
| Which Calendly plan the firm is on | Webhooks are not on the free plan, and the webhook is what stops the office double booking |
| Deposit at booking, or invoice afterwards | Decides whether phase four is in this project or a later one |
| How emergency calls are handled | Whether they jump the calendar or go straight to a phone number |
| How many people the calendar covers | One technician and several are different amounts of work |
| Grocery, today | Plumbing, proposed | |
|---|---|---|
| What a customer asks for | A product | A job doing |
| What the assistant matches against | 25,631 products | Tens of services |
| What they choose | A quantity | A time |
| What ends the conversation | A delivery | A visit |
| Where it runs | Its own server | Its own server, separately |
| What it shares | Nothing at run time |