Diagrams

Overview · Diagrams

Index and shared conventions

Eight views, one altitude each

This page holds the eight architecture diagrams for the Addi platform. Each diagram is one page, one altitude, one question. We keep the pictures deliberately spare: a diagram here exists to show a boundary or a flow of responsibility, never to inventory implementation. Detail that a picture cannot carry honestly lives in the prose spine, the architecture, and each diagram names the spine sections it reads with.

Reading order

Read them in numbered order. The first diagram places the platform in the world; the next six each open one interior mechanism; the last maps concerns to named technologies.

Shared element names

The same thing carries the same name

The same thing carries the same name in every diagram, in the prose spine, and in the unit documents. The registry: the Addi platform, internal operator, self-serve investor, property submitter, the operator's Claude, identity provider, billing processor, licensed property and rental data sources, public government and open-data sources, platform backend, web application, analysis engine, Python compute tier, reference layer, write door, published configuration, entitlement choke point, authorization surface, work queue, consent and audit records, verified address identity, artifact, finding, system field, underwriting assumptions, buy-box verdict. Most definitions live in the glossary; the remainder are defined where their diagram introduces them.

One naming rule worth stating: technologies are named exactly once, in diagram 08. Every other diagram uses the role name (identity provider, billing processor, platform backend) so that the pictures describe responsibilities, not products. This is deliberate: a boundary drawn around a role survives a product swap; a boundary drawn around a brand does not.

Diagram 01 · Context

System context

Scope: the Addi platform as a single system, the people and agents that use it, and every external party it depends on, grouped by who operates what.

Altitude: Context. The platform is one box on purpose; its interior begins at diagram 02.

Intended audience: a technical evaluator forming a first mental model of what we run, what we integrate, and what our customers bring with them.

Notation key: rectangles are systems we build and run; stadium shapes are people or systems operated by others; solid arrows are synchronous requests; dashed arrows are asynchronous or scheduled flows; subgraph boxes are ownership boundaries.

flowchart TB
  subgraph customer["Brought by the customer"]
    operator(["Internal operator"])
    investor(["Self-serve investor"])
    claude(["The operator's Claude"])
  end

  subgraph us["Built and operated by us"]
    addi["The Addi platform"]
  end

  submitter(["Property submitter"])

  subgraph others["Operated by others, integrated by us"]
    idp(["Identity provider"])
    billing(["Billing processor"])
    licensed(["Licensed property and rental data sources"])
    opendata(["Public government and open-data sources"])
  end

  operator -->|"works deals in the browser"| addi
  investor -->|"signs up and analyzes properties, self-serve"| addi
  claude -->|"connects over MCP, authorized with OAuth 2.1 plus PKCE"| addi
  submitter -->|"submits properties by public form or inbound email"| addi
  addi -->|"delegates authentication and org membership"| idp
  addi -->|"settles credit-based billing"| billing
  addi -.->|"reads under license into an owned reference layer"| licensed
  addi -.->|"reads on our schedule into an owned reference layer"| opendata

Element catalog

Diagram 03 · Container

The configuration kernel

Scope: the lifecycle of configuration: authored as a draft, published as one atomic versioned set, rendered by every surface, and enforced server-side when a module is off.

Altitude: Container.

Intended audience: an evaluator probing whether "configurable" means real configuration-as-data with a publish discipline, or a settings page with side effects.

Notation key: rectangles are systems we build and run; stadium shapes are people; diamonds are decision points; solid arrows are synchronous commands; dashed arrows are the deactivation effects of an absent entitlement; subgraph boxes are ownership boundaries.

flowchart TB
  author(["Configuration author"])
  draft["Configuration draft"]
  publish{"Atomic publish"}
  published["Published configuration, versioned"]
  surfaces["Rendering surfaces"]
  choke["Entitlement choke point, fail-closed"]
  doors["Module write doors"]
  jobs["Scheduled jobs"]
  notify["Notifications"]

  author -->|"authors tenants, modules, pipelines, stages, strategies, fields"| draft
  draft -->|"validated set submitted"| publish
  publish -->|"concurrent publish detected: refused, author resolves"| draft
  publish -->|"accepted: becomes the one live set"| published
  published -->|"every surface renders this set; drafts never leak"| surfaces
  published -->|"resolves every entitlement question"| choke
  choke -->|"module on: business commands admitted"| doors
  choke -.->|"module off: writes refuse"| doors
  choke -.->|"module off: jobs deactivate"| jobs
  choke -.->|"module off: notifications drop"| notify

Element catalog

Diagram 05 · Container

The compute seam

Scope: the boundary between the transactional platform backend and the deterministic analysis engine: one async entry point in, one signed callback out, with the engine and its owned reference layer behind the boundary.

Altitude: Container.

Intended audience: an evaluator asking how analysis load and analysis failure are kept out of the transactional system, and how external data dependence is disciplined.

Notation key: rectangles are systems we build and run; cylinders are data we own; solid arrows are synchronous calls; dashed arrows are asynchronous callbacks and offloaded jobs; subgraph boxes are ownership and failure-domain boundaries.

flowchart TB
  backend["Platform backend"]
  entry["One async entry point"]

  subgraph seam["Behind the seam: a separate service, its own failure domain"]
    engine["Analysis engine: deterministic, fail-soft"]
    reference[("Pre-cached national reference layer")]
  end

  python["Python compute tier, serverless"]

  backend -->|"dispatch analysis"| entry
  entry --> engine
  engine -->|"reads, cache-first"| reference
  engine -.->|"source document retrieval, spatial joins, document parsing"| python
  engine -.->|"HMAC-signed callback, tenant echoed, idempotent ingestion"| backend

Element catalog

Diagram 07 · Container

The write law

Scope: the single rule that governs every write to a field, human or machine: machine writes land freely into empty or machine-sourced fields, and never over a human-confirmed value; over a human they become proposals.

Altitude: Container. The diagram shows the write path at door level; the decision flow inside a door is held at Tier 2.

Intended audience: an evaluator asking how a platform full of machine writers, with an autonomous agent among them, avoids ever destroying human judgment.

Notation key: rectangles are systems we build and run; stadium shapes are people or writer roles; cylinders are data we own; solid arrows are the write flow; dashed arrows are recorded outcomes.

flowchart TB
  machine(["Machine writer"])
  humanw(["Human writer"])
  door["Module write door"]
  land["Write lands"]
  proposal["Queued as a proposal; nothing is overwritten"]
  record[("Provenance and decision record")]

  machine --> door
  humanw --> door
  door -->|"the law admits the write"| land
  door -->|"a machine write over a human-confirmed value"| proposal
  land -.-> record
  proposal -.->|"outcome, either way"| record

Element catalog