# The substrate ladder

> Four kinds of software, one architecture: when to connect an external tool, when to declare a tracker, when to build real code, and when the platform builds machinery in-house.

## Every capability lands on one of four substrates

In the age where AI can generate a working application in an afternoon, the scarce skill is no longer building; it is choosing **where** something should live so that it stays governable, auditable, and cheap to keep. Relay's operating doctrine names four substrates and a criterion for each. Most architecture mistakes we see are substrate mistakes: the right thing built on the wrong rung.

### 1. Connect an external tool

Connect when a tool's value is accreted domain machinery you would never sensibly rebuild (a BI query engine, git hosting with CI, a design canvas), or when an external network lives there: counterparties, auditors, communities you cannot onboard. The tell is **depth and network**, never "it mutates data" (records mutate fine on the engine).

Connections are governed, not ambient: one credential custodied by the workspace, typed operations, per-agent grants, and a call ledger. See [Visibility and governance](/docs/visibility#secrets-and-connections).

### 2. Declare it on the tracker engine

Declare a tracker when the need is **record-shaped**: states, reference codes, owners, audiences, receipts, glanceable aggregates. The engine's grammar is limited by design, because records need one consistent idiom more than they need Turing-completeness; the grammar grows by demonstrated pull (charts, child rows, relations, and rollups each arrived that way, in days). See [The tracker model](/docs/the-tracker-model).

### 3. Build it as real code

Build custom when **code computes over the data**: relational joins on bespoke fields, aggregation logic, invariants, novel domain machinery. This is a positive criterion, not a failure of the platform; a record engine that tried to absorb arbitrary computation would become a bad database with a chat client attached. The recorded warning sign on the engine side is join-hunger: the day queries want real joins over declared cells is the day that data has outgrown its substrate and earns a typed home.

### 4. The platform builds machinery in-house

The platform builds deep machinery itself when **fusion with the record-and-governance layer is the product**. Relay's meeting capture is not valuable because its transcription beats a dedicated vendor's; it is valuable because a spoken "I'll do that by Friday" becomes a tracked commitment owed to a named person, on a docket, chased by machinery that never forgets. That property cannot be integrated in from outside, because it lives in the fusion, not in the transcription. The counter-examples are just as deliberate: git hosting and BI stay on rung 1, because their depth is orthogonal to the loop and fusing them would improve nothing.

## The invariants that make it one architecture

**The record converges even when the machinery does not.** The BI tool keeps the dashboards; Relay keeps the registry of them. The git host keeps the code; Relay keeps the record of changes that matter to the workspace. Owning the record while connecting the machinery is what stops rung 1 from quietly becoming a data silo.

**Access is a governed grant, never an ambient credential.** Whatever the rung, agents reach it through identity-bound, revocable, ledgered grants. The substrate changes; the authority model does not.

**Records get one idiom.** Wherever work lands, its record surfaces on Relay with the same reference codes, the same visibility grammar, the same audit trail, and the same socket. A workforce, human or AI, should learn the record language once.

## Why this matters more now, not less

Cheap generation cuts both ways. It makes rung 3 genuinely cheap, which kills the old argument for platforms ("building is slow"). What it cannot cheapen is everything after the build: thirty hand-rolled internal apps are thirty auth surfaces to audit, thirty drifting idioms to learn, thirty places a security review has to re-establish first principles. The bottleneck has moved from writing software to **verifying and governing** it, and that is precisely the work the ladder concentrates onto one engine, one role system, and one trail. The ladder is not a constraint on what you can build; it is the reason you can afford to keep what you build.