Addi · Architecture Disclosure · Tier 1
Our engineering method: how a feature moves from an idea to a promise, from a promise to rules, from rules to code, and from code to production.
Overview · How We Build
The method
This document describes our engineering method: how a feature moves from an idea to a promise, from a promise to rules, from rules to code, and from code to production. We treat the method as part of the architecture. A reader can judge a system's design from its diagrams, but whether the design survives contact with change depends on how the team works, so we document that with the same care as the system itself.
Levels
Every piece of work is settled at three levels, in order.
Level one is the outcome: what done feels like, described per role. For an investor-facing surface that means what the investor can now decide that they could not decide before. For an operator surface it means what the operator no longer has to do by hand. We write this in plain language, before any design, because it is the only level a non-engineer can veto, and we want the veto to happen while it is cheap.
Level two is the logic: the rules that keep each promise in the cases that would break it. Not the happy path. The cases that would break it. If the promise is "a machine never overwrites a human's judgment," level two is the enumeration of every path a machine value can take into a field and what happens on each one. This is where most of the thinking lives.
Level three is the code. When levels one and two are actually settled, the code is mostly transcription. That is not a boast about speed; it is a test. If writing the code surfaces decisions nobody made, the spec was not done, and we go back up.
The common alternative is to start from the data model or from a working prototype and let the promises emerge. It is faster to first output. We do not build that way, because promises that emerge from code are shaped by what the code found convenient, and in a system whose core claims are about provenance and honesty, convenience-shaped promises are the failure mode. The connection between the levels is the discipline: every rule at level two traces to the promise it protects at level one, and every load-bearing piece of code traces to a rule. A rule that protects nothing gets deleted. A promise with no rule under it is not yet real.
Gates
Two gates stand between the levels, and they are the only ceremony in the method.
The first gate: no code until a spec settles levels one and two and receives an explicit go-ahead. The go-ahead is a human act, not a timeout. Work that skips this gate gets stopped even when the code is good, because good code against an unsettled spec is how a codebase accumulates confident wrongness.
The second gate: every load-bearing rule is expressed as code, never as prose. A rule that matters becomes a validator, a typed contract, a server-side check, or a failing test. Prose rules are the ones a future contributor, human or agent, will not read at the moment it counts. We hold this gate especially hard for the rules the platform advertises: the write law, fail-closed entitlements, and tenancy checks are all enforced mechanically at the point of action, not documented and hoped for.
Review
Finished work takes two review passes with different questions.
The program review asks: does the code keep every promise, in the cases that would break it, and is that proven by real tests? Real tests means tests that exercise the breaking case, not tests that restate the implementation. A reviewer in this pass reads the spec first and the code second.
The code review asks the craft questions: security, understandability, and consistency with the rest of the codebase. We keep these passes separate because a reviewer holding both questions at once reliably drops one of them, usually the first.
Done is not merged code. Done includes the live surface holding up against the real backend in all four states a user can meet: loading, empty, error, and content. Empty and error are stated deliberately because they are the states that demos skip and users find. The bar an error state is held to is that it names the exact blocker and the fix, which means the error paths have to be designed, not caught.
Evidence
Before anything is designed net-new, existing systems are swept and cited. The sweep produces a verdict for each piece: rebuild it, reference it and improve it, or build net-new with an explicit citation of what was searched and why nothing fit. Net-new without a sweep is treated as a defect in the process, not a style preference, because the most expensive code in any platform is the second implementation of something that already existed.
Decisions live in a ledger with statuses. Proposals are argued in the ledger, ratified decisions are recorded with their forces and their costs, and superseded decisions stay visible with the reasoning that replaced them. Every draft, spec, and design is checked against the ledger before it reaches a decision maker, so a settled argument does not get re-litigated by accident. Locked rulings are locked: a locked ruling changes only through an explicit reopening, never through drift. Major decisions are framed as context, decision, and consequences, including the negative consequences, and a digest of the ones that shaped this architecture ships with this package (Decisions).
Agents
Part of our code is written by AI agents under human direction. The skeptical reading of that sentence is that quality erodes as volume grows, and we agree that it does under prose discipline, which is why our agent practice has exactly one theme: nothing important is enforced by asking nicely.
Mechanical gates over prose. An instruction to an agent is a hope; a gate is a fact. Where a rule matters, it exists as something that fails: a check the build runs, a contract the type system enforces, a validator at the write door. This is the second gate applied to a workforce that reads instructions selectively and never gets tired of retrying.
The writer is never the auditor. Whoever produced a piece of work, human or agent, does not verify it. Verification runs in a fresh context with no access to the writer's reasoning, because a verifier that shares the writer's context inherits the writer's blind spots. The rule applies to humans and agents alike; with agents it is non-negotiable.
Verification is budgeted, adversarial, and independent. We allocate real capacity to reviewers whose job is to break the work: side-by-side comparison against the reference, tests aimed at the enumerated breaking cases, and fresh-context reads of the finished surface. Verification that is squeezed from leftover budget finds leftover bugs.
Human checkpoints on every product call. Agents implement; they do not decide what the product is. Any choice a user would notice, naming, behavior, what a screen promises, passes through a human. This mirrors the platform's own doctrine: in the product, a recommendation never moves a deal on its own, and in the building of the product, an agent's recommendation never ships on its own.
Delivery
Delivery is deliberately unexciting. Work happens on branches. A hard CI gate stands in front of every merge: type checking is strict, linting and formatting are enforced mechanically, and the test suites (unit-level and browser-level) must pass. The gate is required, not advisory: a red build does not merge. A gate that can be argued with is advice, and advice is exactly what a mechanical gate exists to replace.
Environments are separated, and promotion between them is a staged, human decision rather than an automatic ripple. The internal lane and the public lane are distinct production deployments forked at the infrastructure layer, so a promotion targets one lane explicitly and the blast radius of a mistake is one lane, not the product. Production changes require explicit approval; promotion is the only route work takes to a live surface.
In operation, the same conservatism holds: agent actions and data movement are recorded so they can be inspected after the fact, autonomous work is bounded by budget caps and swept for failures rather than trusted to finish, and a disabled capability is dead at the server, not hidden at the screen. Deploy-time discipline and run-time discipline are the same discipline at two moments.
The lines
A few sentences do a lot of work in our conversations, because they compress a rule to the length at which people actually apply it.
"Cache the data, compute the meaning." No language model sits anywhere in the data producers. Reference data is cached and served; interpretation is deterministic code; the agent's job is synthesis on top of computed truth, never the computing of the truth itself. This is why two runs over the same data agree.
"Free into empty, never over a human." The write law in one line. Machine writes land freely into empty or machine-sourced fields and never over a human-confirmed value; over a human they become proposals, and acceptance stamps the value human-confirmed. It is simultaneously our data-quality rule and our agent-safety contract.
"Feature off means dead." A switched-off module is not hidden, it is inert at the server: writes refuse, scheduled jobs deactivate, notifications drop. Configuration is only trustworthy if off means off.
"The writer is never the auditor." Stated above for agents; applied everywhere, to every piece of work that ships, whoever or whatever produced it.
The boundary
Withheld by design Tier 2
The working artifacts behind this method, the spec and review templates and the checks our build pipeline runs, are held at Tier 2.Withheld by design Tier 3
The operating doctrine served to the agent is held at Tier 3: the architecture spine describes that it exists and how it is served, and the contents themselves are examined only under Tier 3 conditions. The same holds for the data factory's extraction specification and its ladder of quality gates: the module descriptions state that the gates exist and what they protect, and the specification and gate list are held at Tier 3. Live walkthroughs of the method applied to real work are Tier 3 as well, under controlled conditions.This document states the method; the deeper tiers demonstrate it.