The numbered spine
Addi at the level of system boundaries and major runtime responsibilities, and it stays there on purpose. Every other document in the package cites into these numbered sections.
Overview · Architecture
The spine
This is the spine of the disclosure package. Every other document in the package cites into these numbered sections. It is written for senior engineers and technical leaders evaluating our engineering under NDA: detailed enough to assess how we think, deliberately not detailed enough to rebuild from. Where content is withheld, we say so and name the tier that holds it.
Section 1
This document describes Addi at the level of system boundaries and major runtime responsibilities, and it stays there on purpose. We treat abstraction level as a discipline, not a formatting choice: a document that mixes the system's place in the world, the responsibilities of its major parts, and code detail in the same breath is hard to verify, easy to let rot, and leaks more than its author intended. So we declare the altitude once and hold it. You will find system boundaries, responsibilities, guarantees, contract shapes, and the reasoning behind them. You will not find schemas, payloads, field lists, formulas, or step-by-step internals; those live at Tier 2 and Tier 3 as described in section 16.
The guiding test we applied to every line: does this help you vet whether we know our stack, without handing over the means to reproduce it? Anything that only did the latter was cut, and the cut is marked.
Section 2
Four goals shaped every structural decision. We list them with the mechanism that carries each one and the cost we accepted, because a quality goal without a mechanism is a slogan and a mechanism without a named cost is marketing.
Every field value in the system records what produced it: a human, the agent, a report, an import, or a template. Every reported value carries provenance and confidence, in words a non-engineer can read. Two corollaries do real work here. First, data at coarse geographic precision is never presented at finer precision than it has; a value measured over a wide area is never presented as if it were measured on this block. Second, when independent data reads disagree, the disagreement is surfaced as signal rather than averaged into a confident-looking middle. The cost: our surfaces sometimes look less certain than a competitor's single polished number. We consider that the product working, because our users commit serious capital on these values and false confidence is the most expensive defect we could ship.
Tenants, modules, entitlements, pipelines, stages, strategies, and field definitions are data, not code. Changing what a tenant sees is an act of publishing configuration, never of deploying software. The mechanism is the configuration kernel (section 6). The cost: a layer of indirection that every surface must respect, and velocity spent building an authoring and publish path instead of hard-coding any single customer's shape. We paid it because the alternative is a codebase that forks a little with every customer until it is several products wearing one name.
The agent operates under budgets, attribution, and reversibility rather than under human approval gates on each write. The mechanism is the write law (section 8) plus the work queue and budget caps (section 10). Where a capability is genuinely risky, it ships read-only rather than gated. The cost: we had to make provenance a first-class property of every field in the system before the agent could be trusted with any of them. Sections 8 and 10 argue why we believe gates are the weaker safety model, not the stronger one.
One product serves an invite-only internal operator lane and a public self-serve lane, and its isolation options ladder up to physically separate per-customer deployments. The mechanism is the infrastructure-layer fork (section 5) plus module composition and the isolation ladder (section 13). The cost: we forgo per-lane bespoke optimization, and every feature must be built aware that its audience is composed, not assumed.
Section 3
We designed the architecture backward from the failures our domain guarantees. Property intelligence is a domain where the inputs are unreliable by nature, so we treat these as standing conditions, not edge cases. Each one names the section that answers it.
Not stale, wrong: the authoritative source asserts a falsehood about the physical world. Any pipeline that treats government data as ground truth will confidently propagate the error into a purchase decision. Our answer is the corrections mechanism inside the evidence chain: an authoritative human correction short-circuits downstream reads, and the correction itself is recorded (section 9).
External data availability is a distribution, not a constant. Our answer is a pre-cached reference layer with freshness tiers by data kind, and fail-soft producers: one missing source degrades one section of one report with honest confidence, it never blocks the analysis (section 11).
Zoning truth is scattered across municipal ordinances of wildly varying quality, and no external feed solves this. Our answer is to own the asset: an in-house, quality-gated pipeline that turns ordinances into canonical records, paired with honest coverage states in the product, covered, partial, or not yet, with no fabricated completeness (section 12).
The same address is a different concept to intake, zoning, valuation, market analysis, underwriting, and pipeline management, and data arrives in mismatched geographic units. Our answer is twofold: modules share identity but never models (section 7), and the compute engine resolves the address once into the geographic identities its sources require, so every source is queried in its native geography (section 11).
Heavy analysis work fails partway through as a matter of course. Our answer is one async entry point, idempotent ingestion, signed callbacks, and a work queue that recovers failed jobs instead of losing them (sections 10 and 11).
An AI agent given static instructions diverges from the deployed system as the system evolves, and an agent given write access can do damage at machine speed. Our answer is served doctrine, the agent fetches its current operating instructions from the platform at session start, plus the write law bounding what any machine write can touch (sections 8 and 10).
Some of what an agent reads originates outside the platform, and content can be written to manipulate the reader. Our answer is that externally sourced content reaching an agent is treated as data, never as instruction, and ingestion fences plus the write law bound the blast radius of anything that slips through (sections 8 and 10).
Section 4
Six moves carry the whole design. Everything else in this document elaborates one of them.
Tenant shape is data with an atomic, versioned, rollback-able publish cycle. This carries configurability without code and gives "feature off means dead" a single enforcement point.
Who or what produced a value is recorded per field, and that record, not a role check alone, decides what may be overwritten. This carries provenance honesty and is the foundation the write law stands on.
Each business capability owns its tables and exposes exactly one write path, with commands named by the business action they perform. Humans and agents use the same door. This makes the write law enforceable rather than aspirational.
Deterministic analysis runs as a separate service in its own failure domain, reached through one async entry and returning through signed callbacks. This carries the fail-soft answer to unreliable sources and keeps the transactional backend responsive.
Addi is not a chat feature; it is an authenticated principal connecting over an open protocol, with consent, audit, budgets, and the same write doors as everyone else. This carries agent safety by traceability.
The zoning corpus and the market reference layer are built and owned, not licensed, so the honesty doctrine can extend all the way into the data itself: we control the quality gates because we control the pipeline.
The pattern across all six: we spend our complexity budget on boundaries and provenance, and we refuse to spend it on premature infrastructure. Section 11 returns to that trade honestly.
Section 5
Addi ships from one codebase into two production lanes: an invite-only internal operator dashboard and a public self-serve product. The fork between them lives entirely at the infrastructure layer: separate identity instance, separate backend deployment, separate edge project, separate domain. It never lives at the code layer. There is no internal-only branch, no long-lived divergence, no "port this feature to the other product" workstream.
We weighed the alternative, a separate consumer product, and rejected it. Two codebases serving one domain converge on double maintenance and drifting behavior, and the drift shows up exactly where it hurts most: in the numbers. A valuation that differs between the internal tool and the customer product is not two products, it is one broken promise.
What differs between lanes is composition, not code. The configuration kernel and entitlements decide which modules exist for which tenant, and internal-only surfaces (for example, review-and-push tooling) are simply not part of any user-lane tenant's composed module set, which under the kernel's rules means they are dead server-side there, not hidden client-side (section 6). The infrastructure fork then gives the two lanes independent blast radius: an incident in one lane's deployment does not touch the other.
Section 6
The kernel is where "configurability without code" becomes mechanics rather than intention. Tenants, modules, entitlements, pipelines, stages, strategies, and field definitions are data. An administrator authors changes as a draft, and the draft is invisible to every rendering surface until published. Publish is atomic: one versioned set becomes the truth for the tenant, all at once. Concurrent publishes are detected and refused rather than silently merged. Rollback is a forward roll to a prior version's content, which keeps history linear and auditable instead of rewriting it.
Every surface renders the published set. Not "reads a config file", not "checks a flag": the pipeline board, the deal workspace, the calculator's strategy list, and the agent's view of the tenant are all projections of one published configuration version.
The rule with the sharpest teeth is that feature off means dead, server-side. When a module is not in a tenant's composed set, that module's writes refuse, its scheduled jobs deactivate, and its notifications drop. The composed module set is the one switch. We adopted this rule because the alternative, hiding surfaces in the client while the server still accepts their writes, is not a disabled feature, it is an undocumented API. Entitlement resolution happens fail-closed at one choke point: if entitlement cannot be established, the answer is no. A read-only truth view exposes every switch's current state, so "what is actually on for this tenant" is a lookup, never an investigation.
Withheld by design Tier 2
The configuration schema itself, its validation rules, and the authoring surfaces are Tier 2 material.Section 7
The platform is a modular monolith organized by business capability: intake, buy box, pipeline, deal workspace, reports, underwriting, the agent surface, coverage, configuration, and billing. Each module owns its tables by convention, exposes a strict public API, and has exactly one write door. Commands through that door are named by the business action they perform, the vocabulary an operator would use, "verify this submission" or "advance this deal", not a generic mutation vocabulary. Modules announce what happened through events that carry identity plus the business fact, never a data dump; a subscriber that needs more asks the owning module through its public API. Cross-module table reads are prohibited. We are honest about enforcement classes: some of these rules are mechanical, caught at compile time or in continuous integration, and others are held by convention and review, and we say which is which where it matters.
The boundary rule we lean on hardest: modules share identity, never models. We say it internally as "a property is not a property." The same street address is a different concept to intake (a submission to verify and dedupe), to zoning (a parcel inside a jurisdiction's rules), to valuation (a subject with comparables), to market analysis (a location inside overlapping geographies), to underwriting (a bundle of assumptions and cash flows), and to pipeline (a deal at a stage). Forcing those six concepts into one shared model produces the god-object that every team who has tried it knows: a record with dozens of half-owned fields and no invariants anyone can state. Instead, each module holds its own model keyed to a shared verified identity, and the evidence chain (section 9) defines how knowledge flows between them.
Why a modular monolith rather than services? Because the failure isolation we actually need has one location, the analysis engine, and it gets a real process boundary (section 11). Everywhere else, the expensive thing is boundary discipline, not network separation, and discipline enforced by convention, contract, and review travels at monolith speed without distributed-system tax. The write-path and read-path are kept as two distinct paths through each module, which keeps commands auditable and reads composable without the ceremony of full event sourcing.
Section 8
This section and the three after it are the heart of the architecture.
Every field value records its producer class: a human, the agent, a report, an import, or a template. This is not an audit convenience bolted on afterward; the provenance ladder is the write-authorization mechanism. Most systems answer "may this actor write?" with roles. Roles answer the wrong question for a system where machines and humans write into the same fields. The dangerous event is not "an agent wrote a value", it is "an agent destroyed a human judgment." So authorization here depends on what is already in the field, not only on who is writing.
The rule, which we coined internally and use everywhere, is the write law:
Machine writes land freely into empty or machine-sourced fields, and never over a human-confirmed value. A machine write that would collide with a human-confirmed value becomes a proposal instead. Acceptance of a proposal stamps the value human-confirmed.
Three properties fall out of this rule, and they are why we treat it as doctrine rather than a feature.
First, machine work compounds without friction where it is safe. Reports, imports, and the agent can fill and refresh the large machine-owned surface of every deal at machine speed, because writing into empty space or over other machine output destroys no judgment.
Second, human judgment is a ratchet. The moment a person confirms a value, that value leaves the machines' reach. Nothing automated can quietly undo it; it can only argue with it, visibly, through a proposal the human resolves. Escalation is one-way and deliberate.
Third, and this is the part we ask skeptical readers to sit with: the write law is the agent blast-radius contract. Agents get the door, never the tables. An agent write flows through the same business-named command as a human write, lands under the same provenance stamping, and obeys the same law. The worst case for any agent malfunction is therefore bounded by construction: it can pollute machine-sourced space, which is attributable, versioned, and reversible, and it can generate proposals, which are inert until a human acts. It cannot silently overwrite a single human decision.
We weighed the obvious alternative, approval queues on every agent write, and rejected it; the decision and its consequences are recorded in the decisions digest. Universal review queues fail in a predictable way: volume turns review into rubber-stamping, rubber-stamping launders machine output into "human approved" without human judgment, and accountability blurs at exactly the moment it should sharpen. The write law inverts the economics. Machines act freely where no judgment is at stake, and human attention is spent only where a machine disagrees with a human. Gates ration machine work; the write law rations human attention. The second resource is the scarce one.
Section 9
Knowledge in Addi flows one way: versioned artifacts produce structured findings; findings project into editable system fields; fields feed underwriting assumptions. Each link has a deliberate character.
A property is a folder of versioned artifacts. Re-running an analysis creates a new version; it does not mutate the old one. What a report said on the day a decision was made remains inspectable afterward, which is the difference between an audit trail and a comforting story.
A finding is a structured fact extracted from an artifact, and it stays exactly what the artifact produced. Findings project into system fields, which humans may edit, and which sit alongside operator-authored custom fields. This split resolves the tension every data product faces between machine truth and human correction: we keep both, separated by provenance, instead of letting edits corrupt the record of what the machine actually found.
The calculator does not reach into a report's guts; it reads the projected, provenance-stamped surface. Report internals can be reshaped without a blast radius in the numbers that price a deal.
Every surface reads a contract shaped for its question, which is what lets storage change underneath a stable shape (this matters again at the warehouse seam, section 11).
The chain runs one way because circular evidence is the failure mode of intelligence systems: a derived value leaks back into an input, and the system begins citing itself with growing confidence. One-way flow plus per-value provenance means every number on a decision surface can answer "where did you come from" all the way down.
One deliberate exception proves the rule. Because public records are sometimes wrong (section 3), an authoritative human correction can short-circuit downstream reads: consumers see the corrected value instead of the source value. The correction is itself recorded as a first-class event, with the original preserved. Honesty here means the system neither stubbornly repeats a known-wrong record nor quietly pretends the record always said the corrected thing.
Section 10
There is no in-app chat. We consider that a load-bearing decision, so we will defend it before describing the machinery.
The people Addi serves already have an AI assistant they know and trust: their own Claude. Embedding a chatbot would make us a middleman reselling intelligence through a worse interface we would then have to meter, maintain, and prompt-engineer forever. Instead, the operator's own Claude connects to Addi over MCP, the open Model Context Protocol, and Addi presents itself as what it actually is: a system the agent works in, with real capabilities, real permissions, and real accountability. The agent is a first-class principal, not a feature.
The connection surface is built into the backend and implements OAuth 2.1 with PKCE: dynamic client registration, RS256-signed tokens, scoped access, and consent and audit modeled as schema rather than as log lines, so "what did the operator authorize and what did the agent do" are queryable facts. Defense in depth is boring on purpose: every tool call independently re-verifies tenant identity rather than trusting a session established earlier.
Two mechanisms keep agent behavior aligned with deployed truth. First, served doctrine: the agent fetches its current operating instructions from the platform at session start, so the doctrine it is offered is always current with what is actually deployed, which is our structural answer to the agent-drift failure in section 3. Second, a mechanical house-style gate at the write door checks agent-authored output before it lands; style and safety rules that live in prose get forgotten, rules that live in a gate do not.
Withheld by design Tier 2 Tier 3
The tool catalog and scope topology are Tier 2; doctrine contents are held at Tier 3.Autonomous work is a queue, not a scheduler fantasy: a small set of autonomous job kinds, worked through a work queue that recovers failed jobs instead of losing them, under budget caps. Budget caps mean a malfunctioning or runaway session exhausts an allowance, not a wallet, and autonomy is deliberately budget-capped while trust accrues; loosening a cap is an explicit decision with a track record behind it, not a default.
Now the objection we expect from every serious reader: you gave an autonomous agent write access to production data?
Yes, and we will argue the design is safer than the gated alternative. The agent has no table access of any kind; it holds a scoped token to business-named commands behind the same write doors humans use. Under the write law, every write it can perform is one of exactly two things: a landing into empty or machine-sourced space, which is attributed, versioned, and reversible, or a proposal against a human-confirmed value, which is inert until a human accepts it. Every action is tenant-verified per call, consent-bound, budget-capped, and audited as schema. And where we judge a capability genuinely risky, we do not gate it, we ship it read-only, because a read-only capability has no failure mode that needs reviewing. Safety here is budgets plus traceability plus reversibility. Approval gates on writes were considered and rejected on the argument in section 8: they degrade into rubber-stamping and make accountability worse, not better. If you disagree, section 8 is the argument to attack, and we would genuinely welcome that conversation.
Section 11
The compute split follows the grain of the work. The reactive TypeScript backend owns everything transactional and HTTP-shaped: it is where writes, entitlements, configuration, and live surfaces live. Deterministic analysis, the work that turns an address into four reports, runs as a separate service behind one seam, in its own failure domain. Genuinely heavy Python work, source document retrieval, spatial joins, document parsing, runs on a serverless Python tier. An analysis that misbehaves cannot degrade the application serving users; the seam is a firewall between "the product is up" and "an analysis is struggling."
The seam has one shape on purpose. One async entry point dispatches work. Results return through HMAC-signed callbacks, so the backend accepts results only from the engine it dispatched to. Ingestion is idempotent, so a retried or duplicated callback cannot double-apply. Every callback echoes tenant identity, which the backend verifies, so a result cannot land in the wrong tenant even if something upstream confuses itself. The contract includes these four properties, single entry, signed return, idempotent ingest, tenant echo, and their simplicity is why the engine can evolve aggressively behind it.
Inside the engine, the doctrine is a phrase we coined and use everywhere: cache the data, compute the meaning. The engine resolves the address once into the geographic identities its sources require and queries every source in its native geography, which is the structural answer to ambiguous geography. Reference data is pre-cached nationally and served locally at analysis time, cache-first with freshness tiers by data kind, so an analysis is fast and cheap because the data was already there. External access is rate-gated through one governor. Producers are fail-soft: one missing source never blocks the analysis; it lowers stated confidence for the affected section, honestly.
And deliberately: no language model anywhere in the data producers. Interpretation of data is deterministic code, testable and reproducible; the same inputs produce the same reports. Synthesis and grading, the judgment work, belong to the agent, above the evidence chain, under the write law. We rejected generative reports because a report that cannot be reproduced cannot be audited, and our entire value rests on auditability.
Withheld by design Tier 3
Producer internals, freshness values, matching and adjustment mechanics, and all source identities are held at Tier 3.The warehouse seam is the second boundary. All reference data is reached through one access module; producers never touch storage directly. The storage engine behind that module is swappable by design, with a Postgres and PostGIS pattern as the designed target, and the swap is a one-module change when scale demands it, touching zero producers.
Which sets up the second objection we expect: why not a proper warehouse from day one?
Because the boundary is the part that is expensive to retrofit, and the infrastructure is not. Our operating rule is build the path, not the infrastructure. A dedicated spatial warehouse stood up before demand justifies it consumes exactly the attention a small team cannot spare, on capacity planning, migrations, and operational surface, while delivering nothing the access module does not already deliver at current scale. The mistake teams actually regret is not "we adopted the warehouse late"; it is "we let every producer grow its own storage assumptions, and now the move touches everything." The access-module boundary is built and enforced today to prevent the second mistake and leave the first one cheap. The honest cost: until the swap, the access module absorbs work a dedicated spatial store would do natively, and we carry that knowingly. Deliberate debt is still debt; it stays on the books with a trigger, which is what the limitations register in this package is for. When scale demands the move, the boundary is built to make it one module, one migration, zero producer changes. We state that as a design, not a track record: the swap has not been exercised in anger, and what we can demonstrate today is the boundary discipline that keeps it cheap.
Section 12
Two owned data assets sit under the platform. We describe them as concepts and discipline, with no quantities anywhere in this package; scale figures are Tier 3.
An in-house pipeline turns municipal zoning ordinances into canonical, investor-readable jurisdiction records. Zoning is the domain where our failure model says no feed will save you, so we built the factory and own its quality bar. The founding rules are strict enough to be worth stating: nothing invented and nothing silently missing; the writer is never the auditor, meaning every record faces independent quality control; a binding extraction specification with a ladder of quality gates that check each record at more than one altitude; and conservative matching, with honest confidence attached. The corpus is a growing, compounding asset: every jurisdiction added is owned forever, at a quality bar we control.
Withheld by design Tier 3
The specification contents, the gate list, source acquisition methods, and throughput are held at Tier 3.A nationally pre-cached layer of market reference data, served locally to the analysis engine at run time, which is what makes cache the data, compute the meaning economically real. It draws on public government and open-data sources and licensed property and rental data sources.
Withheld by design Tier 3
Source identities are Tier 3.These are owned assets, not licensed feeds, and that distinction carries the honesty doctrine into the data itself. A licensed feed's quality is someone else's roadmap. Our quality gates are ours, which is why the product can say covered, partial, or not yet, and mean it (the coverage module exists to say exactly that, with a request flow for what is missing and no fabricated completeness).
Section 13
Every record carries its tenant. Enforcement happens at one verified choke point rather than being re-implemented per module, because tenancy checks scattered through a codebase are a defect class, and a single choke point is a testable property. Entitlement resolution is fail-closed: no resolution, no access.
Identity is org-based with a clean division of labor: the identity provider owns authentication and organization membership; the application owns roles and privileges. We hold that line because the two concerns evolve at different speeds, and platforms that blur them end up with permission logic half in the identity system and half in the app, which is to say nowhere.
Isolation is a ladder, not a single answer. The default rung is shared infrastructure with logical isolation enforced at the choke point. The top rung is physically separate per-customer deployments, and we climb to it where agent blast-radius demands it, not everywhere. We will state the honest version: logical boundaries are not physical boundaries, and we do not pretend otherwise. The ladder exists precisely so the isolation level is a per-customer decision matched to what their agent is authorized to do, rather than a one-size answer that is either wasteful or insufficient.
Section 14
Delivery mechanics, stated as properties and controls.
The two production lanes run on separate infrastructure end to end (section 5), so a change reaching one lane is not exposure in the other; each lane's blast radius is its own.
Definition of done includes the live surface, not just the suite: a feature is done when its surface holds up against the real backend in all four states, loading, empty, error, and content. In the underwriting calculator, the surface that prices a deal, error states name the exact blocker and the fix, because "something went wrong" is an unowned failure in front of a capital decision.
Operationally, the audit posture from section 10 does double duty: consent and actions recorded as schema make agent activity inspectable after the fact, and per-value provenance makes data movement inspectable at any time. Autonomous work runs under budget caps by construction, so cost and blast radius are bounded before any job runs, not reconstructed after. Scheduled work belonging to disabled modules is dead server-side, so the running system matches the published configuration with no ghost jobs.
Withheld by design Tier 2
Deeper delivery and operational detail, the integration and promotion mechanics between environments, dashboards, alerting, and the runbook layer, is Tier 2.Section 15
Concern to choice, at naming level only. Reasoning lives in the sections above and in the decisions digest.
| Concern | Choice |
|---|---|
| Web application framework | SvelteKit with Svelte 5 (runes) |
| Application language | TypeScript, strict mode |
| Styling | Tailwind CSS |
| Reactive database and backend functions | Convex |
| Identity and organizations | Clerk |
| Edge hosting and edge workers | Cloudflare Pages and Workers |
| Server-side orchestration | Effect (server-side only) |
| Runtime and tooling | Bun, Vite |
| Testing | Vitest, Playwright |
| Heavy compute language | Python |
| Serverless Python compute | Modal |
| Designed warehouse target pattern | Postgres with PostGIS |
| Billing processor | Stripe |
| Agent runtime | Anthropic Claude |
| Agent connectivity | MCP (Model Context Protocol) |
| Agent authorization | OAuth 2.1 with PKCE |
| Token and callback integrity | RS256 JWT, HMAC-SHA256 signing |
| Lint and formatting | ESLint, Prettier |
Withheld by design Tier 2
Versions, configuration, and integration detail are Tier 2.Section 16
This package is Tier 1. The following is withheld by design, each item with the tier that holds it and the reason. Nothing on this list is missing by accident.
Deployment identifiers, internal hostnames, credentials topology, and personnel specifics. These are operational hygiene, not disclosure material, and no tier ever includes them.
If a question you consider essential is not answered by this package or by the tiers above, we would rather hear the question than have you infer the answer. The traceability document maps every reader concern we anticipated to the sections that answer it, including the withheld rows.