Subsystem Architecture — The Map
High-level only: what each subsystem is and how it behaves. No prompt tuning, no chat-behavior details. The point is the shape they share.
6 min
One actor, one repeating shape. There is exactly one thing that thinks-and-talks (the conductor) and one thing that remembers (the policy graph). Everything else is a vertical that follows the same five-step contract: sense a signal, ask the graph what to do, drop a job, wait, then finish the work when the answer comes back. Adding a capability = adding a vertical. The conductor never grows.
Steps ② and ⑤ talk to the brain; ③ and ④ ride the queue; ⑤ uses the hands. Three shared spines, one actor, reused by every vertical.
The shared spines
Not subsystems that "run" — they're infrastructure every vertical leans on. A library, a queue, a set of hands.
Policy Graph
BRAIN · librarybuiltdarkOwns: the company's standing rules + the immutable log of every decision.
find_policy(trigger)→ a tiered answer (rule / observed default / nothing) plus any emerging-pattern observation.log_event(...)→ append one decision; re-fold the projection.policies = fold(events), recomputable and rollback-able.
Never: acts on the world, talks to the PM, holds a queue, or calls a model. It answers and remembers — that's all.
Jobs Queue
ATTENTION · busbuiltdarkOwns: the single durable inbox of everything that needs the PM.
- Idempotent enqueue (one open job per
dedupe_key), priority, andnot_beforetiming. - Lifecycle:
pending → asking → awaiting_reply → resolved. Carriessource(route the answer home) +resume(rebuild the work).
Never: decides, executes, or talks. It's the road, not a traveller. Producers = any vertical; consumer = the conductor, alone.
Workflows
HANDS · execution unittools existrunner neededOwns: the named, gated units of action. The raw tools —
dispatch_vendor, text_tenant, update_issue — live inside workflows; nothing reaches them directly.- A workflow is an ordered recipe of tool steps with bound args. You reach action only by naming a workflow (
run_workflow), never by calling a raw tool. - Deterministic — no model in the loop. The policy graph already speaks this language: a rule says "run workflow Z," and Z is exactly this.
Never: talks to the PM or decides what to do. It only carries out an already-made decision.
The actor
The one subsystem that thinks and speaks. Everything above is passive until it acts.
Conductor
VOICE · the one-job agentto buildOwns: the entire relationship with the PM. The only thing with a mouth.
- Paces the queue — surfaces one ask at a time per chat, respects priority + quiet hours, batches related asks.
- Asks & interprets — phrases a job's question in voice, then turns the PM's reply into a structured
resolution. - Handles spontaneous statements — recognizes "always use Kori for handyman" as a rule and records it via the graph. Recognizing it is its job.
Never: dispatches a vendor or texts a tenant (the hands do that). It reads and records; it doesn't act on the world.
Locked invariant. The conductor has exactly three verbs:
find_policy (read memory), log_event (write memory), and run_workflow (act, gated) — plus plain talk. It can never name a raw action like dispatch_vendor. That one chokepoint is the safety property: the agent goes through memory and workflows for everything, so a misfire is a bad workflow call, never a rogue tool call.The reasoning workers
The conductor stays conversational because it is not the only thing that can think. Reasoning is distributed: a vertical may own a headless, scoped worker that resolves things in its own lane — and bothers the conductor only when a human is genuinely needed.
Worker
REASONING · headless · per-vertical, optionalclassifier existsOwns: judgment inside one domain — triage, classification, reading a vendor's reply — without touching the PM.
- Anything from a single structured LLM call (your trade classifier) to a small tool-using loop. Returns structured data to its vertical.
- Escalates by enqueueing a job, never by talking. "Thursday instead?" it resolves itself; a cancellation with no backup becomes a job for the conductor.
- Still behind the chokepoint — when a worker acts, it runs a workflow, never a raw tool. The invariant binds everyone, not just the conductor.
Never: talks to the PM, and isn't added reflexively. No judgment required (the clock's stale-WO scan is SQL) → no worker. Reach for one only where there's genuine ambiguity.
The verticals
Each owns one kind of work and follows the five-step contract identically. This is where new capability gets added.
PMS Intake
VERTICALOwns: turning a raw work order into a vendor decision the PM confirms.
- Sense: a new
issues_v2row. Consult: classify the trade →find_policy. - Enqueue: a
confirm_dispatchjob. Finish: on yes, dispatch + log the decision.
Replaces: the one-shot LLM that guessed "24/7 electric." No more guessed vendors.
Memory Curation
VERTICALOwns: growing the rulebook — turning repeated patterns into named rules, with consent.
- Sense: an
observationfromfind_policy(one vendor dominating ≥2 scopes, no rule yet). - Enqueue: an
ask_promotionjob. Finish: on yes,log_event(create_policy)— authority gets a name.
Never: promotes silently. A rule is born only from a PM's explicit yes.
Clock / Vigilance
VERTICALOwns: making sure nothing falls through the cracks over time.
- Sense: a tick. Scan for stale states — WO awaiting the PM too long, vendor gone quiet, follow-up due.
- Enqueue: nudge jobs idempotently. Finish: the conductor handles them like any other job.
Never: texts the PM directly or runs its own firehose. Time becomes jobs, paced through the one channel.
Ingest
VERTICAL · sensesOwns: turning the messy outside world into clean, typed events.
- Members: chat-poller (PM texts), issue-poller (PMS work orders), clock (time), reply-watchers (vendor/tenant — later).
- Behavior: detect, debounce, route to the right workspace, hand off. PM chat goes straight to the conductor; the rest feed a vertical.
Never: decides, asks, or acts. Dumb pipes by design.
The contract every vertical shares
This is the actual architecture — not the boxes, but the fact that they're the same box. Any new capability (lease renewals, owner reporting, inspection scheduling) is just another vertical that implements these five steps. None of them touch the conductor's code.
- Sense — a source produces a typed event.
- Consult —
find_policy(trigger)when the decision has a policy dimension (skip if it doesn't). - Enqueue — drop a job with
source,askhint, andresumepayload. - Conduct — the conductor asks the PM and writes a structured
resolution. (Shared; not yours to build.) - Finish — your
sourcehandler executes the work andlog_events the decision, so step ② is smarter next time.
The whole design in one line: the conductor is the only actor that talks — reasoning is distributed to headless workers, and every action by anyone goes through a workflow. A new feature adds a vertical (and maybe a worker); it never makes the conductor bigger. That's how the chat agent gets exactly one job and keeps it.