System design · hld.md and lld.md
From public records to a rep's next door
Four views of the system: the containers and trust boundaries, the Python modules, the tables, and the sequences behind the four flows that matter. Press Play to walk a flow over the architecture, click any box to see what it does and light its calls, or step through a sequence one message at a time. Switch between what production would run and what this demo actually runs.
HLD · hld.md §1-§3
Containers and trust boundaries
People on the left, the app inside the access-code boundary (TB-1), the pipeline in the middle, public sources and the model API on the right. Dashed regions are trust boundaries; dashed boxes are outside services.
Pick a flow, then press Play or Step.
playing flow stepcalls of the box you clicked
eval/report.json and eval/backtest.json, and calibrate only checks the frozen exponents. On a phone the diagram scrolls sideways and follows the flow.hld.md §1
Production shape vs what M1 runs
The demo keeps the production boundaries and contracts and swaps the heavy parts for the simplest thing that behaves the same.
| Id | Container | Production | Demo (M1) |
|---|
LLD · lld.md §2
Modules
One Python package, src/otn/: the 17 modules lld.md numbers plus ingest, imagery and calibrate, which the code added. Click a module for its public functions and to light what it calls.
db, http and config are used by most modules, so each card lists them instead of drawing them. Only discover, vision and evals can spend money, and each goes through budget first (INV-3).ERD · lld.md §1, src/otn/db.py
Tables
SQLite in the demo, the same tables in Postgres + PostGIS in production. Hover or focus a table to see its relations.
Everything hangs off doors (one row per single-family home, key = the parcel's GIS PIN). No owner name or owner mailing address column exists anywhere (INV-1).
Evals → score
Vision quality gate and score calibration
A vision signal feeds the score only if it passes the blind eval.
| Signal | Gate | Precision | Predicted yes | Judged by |
|---|
The score is calibrated on a time split.
Sequences
The four flows, one message at a time
Press Step to advance; the message and its line in the list light up together. All four are drawn at the same scale.
hld.md §3-§4
Trust boundaries and invariants
What may cross each line, and the rules every module keeps.
TB-1 internet → app
Public: the landing page, the hex heat map (≥ 5 homes per hex), evals and this page. Door data, routes, draw-area and /mcp need the access code (header, ?code=, or a session cookie for pages: a random token made at login, held server-side by its SHA-256 with an expiry, revoked on sign-out and never derived from the code; /mcp never accepts the cookie). Production: per-user OAuth and an audit log.
TB-2 vision → model API
Only overhead crops of roofs and yards leave. No address, no parcel id, no name in any prompt.
TB-3 harvest boundary
Owner name and owner mailing fields are dropped in the harvester before anything is stored. The absentee flag is computed in memory and only the boolean is kept.
| Id | Invariant |
|---|---|
| INV-1 | No owner names or owner mailing addresses in the store, logs, prompts or git. |
| INV-2 | Every displayed reason has a source and a date; inferred values are flagged and excluded from evals. A vision signal counts only when it passes the blind-label quality gate, and its measured precision is shown with it. |
| INV-3 | Every paid call goes through the spend ledger and stops at the cap. |
| INV-4 | Read paths (API, MCP, map) make zero paid calls. |
| INV-5 | Eval labels are created without seeing the model's output for that door. |
| INV-6 | No Google Maps Platform content anywhere. |