The Service Assistant

1Purpose and scope

The Service Assistant is the front door to a housing association. Residents ask it about the rules, book a tradesperson, pay for the work, and get a parking pass for a visitor. Providers run their own listings on it. The office runs the association on it. All of it happens in one conversation, and none of it requires telephoning anybody.

This document specifies what it is required to do and how it is required to behave. It is written to be read by somebody who will not read the code, so it names no internal parts. Where a figure is measured it says so, and where a figure is a target it says that instead.

The five qualities in section 5 are the ones this system is judged on: scalability, fallback, availability, security and observability. Each one names the scenario in section 8 that demonstrates it.

2The system in one picture

Four kinds of person arrive, at one front door, and what they came for decides which of four lanes they take. Only the first lane involves a language model.

3Who uses it

A provider sees only their own business. An office user is the only actor who can change what the system knows, and every one of those actions is recorded.

4What it does

Grouped by the part of the product they belong to. Only the second group involves a language model.

Everybody, whatever they came for

1. FR-1Offer one conversation as the way in, and work out from what somebody types or says whether they want the rules, a tradesperson, a parking pass, or something else. Every screen in the product is reachable without knowing it exists.
2. FR-2Know which community a person belongs to, remember it, and scope everything they see to it: their documents, their rules, their parking.

Asking about the rules

1. FR-3Answer a resident's question from their own association's documents, in plain words.
2. FR-4Say plainly when the documents do not cover the question, and list what that association does hold.
3. FR-5Show the document every answer came from, named and ready to open or download.
4. FR-6Accept a spoken question and reply out loud, as an alternative to typing.

Getting work done

1. FR-7Take a description of a problem in the resident's own words and find tradespeople who handle it.
2. FR-8Show a chosen provider's real free times, from their own diary, and take a booking in one step.
3. FR-9Take payment by card, by PayPal, or in cash on the day, and allow a tip that belongs entirely to the provider.
4. FR-10Keep a record of a problem even when it does not become a booking, so the office can see what residents needed and nobody covered.

Parking

1. FR-11Issue a visitor parking pass carrying a code, without a telephone call to the office.
2. FR-12Let gate staff check that code on a phone and see at arm's length whether it is valid, and record the vehicle leaving.

Providers running their own business

1. FR-13Let a provider maintain their own listing, prices, working hours and closures without contacting us, and see only their own business.
2. FR-14Hold a new provider's application until the office approves it, so anybody may apply and only the office decides who is bookable.

The office

1. FR-15Add or withdraw a community document, and have it answerable within seconds, without a deployment.
2. FR-16Choose which engine writes the answers, and start or stop the hardware behind it.
3. FR-17See what the system has been doing: bookings, payments, passes issued, and which engine answered.

5How it must behave

The five qualities the system is judged on. Each names the scenario in section 8 that shows it happening.

5.1Scalability

1. NFR-1Serve at least 150 residents asking questions at the same time without an answer taking longer than 4 seconds at the 95th percentile.
2. NFR-2Queue rather than refuse when demand exceeds capacity, and shed load in a stated, visible way rather than failing silently.
3. NFR-3Add a community, or a document, without redeploying and without slowing existing communities.

5.2Fallback

1. NFR-4When the documents do not support an answer, refuse. No engine is called and no answer is composed, so there is nothing that could be wrong.
2. NFR-5When the chosen engine is unavailable, route to the other one automatically, without a person deciding and without the resident noticing.
3. NFR-6When no engine is available at all, reply with plain composed text rather than an error.

Three layers, in that order. The first is the important one: a refusal is a small annoyance, and an invented rule about somebody's home is not.

Between the two engines the behaviour is a circuit breaker: repeated failures route traffic away, and recovery is tested with a single request before traffic returns. It is built as a cached health reading rather than as a formal breaker, but that is the shape of it.

5.3Availability

1. NFR-7No single component may be able to take the service down. Losing an engine, the hardware behind it, or the network to it must cost quality, never availability.
2. NFR-8Switching engines, adding documents and starting or stopping hardware must all happen without an interruption in service.

The number that matters is not uptime, which is easy to claim. It is requests dropped, which should be zero through every scenario in section 8, including the ones that break things on purpose.

Note what section 2 makes visible: only one of the four lanes uses a language model at all. An engine failing degrades that lane, and even then it falls back. Bookings, parking passes and payments do not notice, because there is nothing in them that could.

5.4Security

1. NFR-9One association's documents must never answer another association's question, whatever the question says and however well the text matches.
2. NFR-10Passwords are never stored, only an irreversible derivation of them at 480,000 rounds. Sessions are revocable and only their hash is kept.
3. NFR-11Repeated failed sign-ins are throttled per account and per address.
4. NFR-12A refusal must reveal nothing. Being told a document exists elsewhere is itself a disclosure.

NFR-9 is enforced before ranking rather than after it, so a document belonging to another association is never a candidate in the first place. It cannot be reached by phrasing a question cleverly.

5.5Observability

1. NFR-13Every answer records which engine produced it, so nobody can claim work the other engine did.
2. NFR-14The office can see, without asking us, what the system is doing: what answered, what was refused, what was turned away, and what the hardware is costing.

The console in section 8 is this requirement drawn out. Everything on it is a thing the system is required to be able to tell you about itself.

6Assumptions and limits

1. A-1The associations supply their own documents. The quality of the answers is bounded by the quality and completeness of what is supplied, and four of the six communities currently hold very little.
2. A-2A scanned page is a picture. It can be stored and handed out but it cannot be answered from.
3. A-3Production runs a single process on a 1GB machine and is at the limit of it. See 5.1.
4. A-4Card and PayPal confirmation depends on the payment provider being able to reach us. Those addresses are not yet registered, so online payment cannot confirm itself in production today.
5. A-5Backups are taken by hand. There is no automatic schedule.

7Out of scope

Deliberate exclusions, not gaps.

1. X-1Reading scanned documents. A wrong figure taken from a bad scan becomes a rule about somebody's home.
2. X-2Answering one association from another's rules, under any circumstances.
3. X-3Learning from conversations. Nothing a resident asks changes what anybody else is told.
4. X-4Choosing between documents that contradict each other. Both are reported, each against its source, because choosing would mean inventing a rule.
5. X-5Legal advice, and any question the documents do not answer.

8Fig. 1, the live model

A working model of section 2, running now, carrying the mix a real morning carries: questions about the rules, people booking a tradesperson, parking passes, payments, and the office at work.

Press a scenario and watch the counters. Two hold throughout, whatever you break: dropped stays at zero and uptime stays at 100%. And when you kill the GPU, watch bookings and passes carry on climbing at full speed, because nothing in those lanes was ever asking an engine for anything.

A model of the design, not a measurement of the server. Engine speeds are taken from measured figures; the load behaviour is modelled.