Keysproperty operations Corbelstone Residential
Architecture in ten minutesIn fullKnown gapsdocs/architecture.md

Keys: the design in ten minutes

Keys is an operator for a residential property manager's daily work: rent, renewals, empty homes, repairs, vendors, statutory inspections and building alarms. It finds what goes wrong, fixes what a written rulebook allows, asks a person for the rest, writes down why, and grades itself against an answer key. The full design goes one level deeper; known gaps says what it does not do.

The running copy works on a synthetic world: an invented company, Corbelstone Residential, with 120 buildings and 8,000 homes in three invented cities. Every figure below comes from the seed 23 world and its replay (commands in the README).

1. One morning

Monday 2 November is the first working day of the month. 1 November was a Sunday, so the rent run lands on the 2nd: 5,955 rent payments post that day (4,915 of them direct debits), 5,503 before 08:00. The weekend's repair calls are waiting, and 96 new tickets arrive between 08:00 and 20:00. The lettings team sends its monthly renewal run, 622 offers, and a few of them are keyed outside the band. Vendors send their monthly invoices, some for jobs they were never sent to. A leak sensor in a plant room has been raising an alarm for twenty minutes and nobody has opened a ticket. The only working lift in an eight-floor block stops.

A good operations team catches each of these, eventually. Keys sees them as they happen, does the routine part at once, and puts the rest in front of the right person with the evidence attached.

2. The parts

 world (DuckDB) ──► definitions ──► detectors ──► workers ──► controller ──► tools ──► world
        ▲              (YAML+SQL)     (cadence)    (rules or    (policy.yaml)  (snapshot,
        │                                           model)           │          undo)
        │                                                            ▼
        └──────────── recal (answer key) ◄──────── ledger ◄──── queue (tier 2, people)
  1. Definitions (keys/dictionary/definitions/*.yaml). Each sector term and each detector is written once, in SQL, with an owner, a version and tests: arrears, in SLA, vacant, renewal window, occupied, open ticket, band price, and the ten incident kinds. The detectors, the operator, the main screen and Ask all read the same files.
  2. Detectors run those definitions on the schedule the policy sets: building problems (water alarms, lifts, duplicate tickets, SLA) at every step, offers and invoices hourly, rent, renewals, vacancies and inspections daily at 08:00.
  3. Workers propose one action per incident. When the runbook leaves one action, a fixed rule fills it in. The model is asked only where there is a real choice (dispatch, re-dispatch or replace a vendor; remind or go to legal; list a home or offer a concession).
  4. The controller checks every proposal against keys/agent/policy.yaml. The action must exist and be allowed for this kind; its arguments must name only things in the evidence; a rent must sit inside the band the evidence names; a vendor must be one the evidence lists; cooldowns, dedupe windows and budgets must allow it. It is plain code, separate from the model, and a model answer cannot talk it round.
  5. Tools make the change: a letter row, an offer, a dispatch, an invoice hold, a ticket from an alarm. Each records a before-snapshot so it can be undone.
  6. The ledger keeps every row, appended and never edited.
  7. The queue holds tier 2 proposals for a person. In the replay a scripted on-call shift answers it (a duty manager, a lettings lead, a credit control lead and a maintenance lead, each with written rules and delays).
  8. Recal scores the ledger against the answer key the world generator wrote.

3. Authority

Anything not listed in the policy is tier 3.

TierMeaningExamples
0Just do itarrears reminder on the schedule, renewal offer at the band price, dispatch a panel vendor inside the SLA, ticket from an alarm, merge a duplicate, hold an unmatched invoice, book an inspection, list an empty home
1Do it and tellreassign a vendor after a no-show, a notice to residents; the building manager is told
2Ask firstlegal notice, rent concession, take a vendor off the panel, re-issue an offer a tenant already holds
3Nevereviction, a price outside the band, contacting a tenant about a legal matter, paying an invoice

Budgets: six automatic actions per building per hour, thirty a minute across the portfolio, forty a minute for the back office (letters, offers, invoices). A building over its budget goes to a person with the reason; a portfolio over its rate waits a minute. The same problem on the same thing is handled once per fifteen minutes, and each action carries its own cooldown (one arrears reminder per lease every two days, at most).

4. A ledger row

Row #484 of the seed 23 replay, at 13:00 on the busy day:

Every row of every kind has the same parts. An approval, a rejection or an undo is a new row pointing at its parent.

5. The screens

6. The busy day in numbers

Between 08:00 and 20:00 on seed 23 the ledger gains 72 rows (SELECT action, status, count(*) FROM ledger WHERE "at" >= '2026-11-02 08:00' GROUP BY ALL on out/keys-replayed.duckdb):

ActionRowsWhat happened
reissue_renewal_offer3216 offers outside the band put to the lettings lead, 16 approvals
hold_invoice15invoices with no matching job held before the payment run, the vendor asked for the job number
open_ticket_from_alarm9four leak alarms and five lone-lift faults ticketed, a vendor dispatched
merge_duplicate_ticket6second reports of one fault merged into the original
notify_residents5residents of a building with no working lift told, the building manager informed
dispatch_vendor, reassign_vendor3tickets past half their SLA with no vendor, or a vendor who did not come
offer_rent_concession2a home empty 104 days: proposed, then approved by the duty manager

7. Measuring it

The generator plants ten kinds of fault and writes each into incidents_truth: the kind, when it starts and ends, the home, lease, offer, ticket, invoice, alarm or building it is about, and the correct handling. The replay runs the operator over six days of history and the busy day on a copy of the world and scores it: precision and recall per kind, the share handled without a person, reverts, time to resolve, decided by rules versus the model, and the weakest detector.

On seed 23 the replayed week scores 98.6% precision and 99.4% recall on 319 planted faults; 85.1% of incidents are handled without a person; the weakest detector is duplicate ticket at 88.5% precision. Thresholds were tuned on seeds 7 and 11 only; seed 23 is the hold-out.

8. Plugging in

Read-only readers for the property management system, the rent ledger, the help desk, the purchase ledger and the building management system map onto the same tables (keys/world/schema.sql). Shadow mode (KEYS_SHADOW=1) writes "would do" rows and changes nothing. A few weeks of shadow rows, reviewed by the operations team, set the tiers before any action reaches a tenant or a vendor.