Engineering overview
Internal. This section is built only when DOCS_INTERNAL=1 and is marked noindex. It states
plainly which components have never handled real money, which are declared but not wired, and where
the traps are. Do not deploy it to a public host.
This section documents apps/api — the backend that holds the money. It is written for someone
about to change code, not for someone evaluating the product. For the product, start at
Overview.
The one principle
Only evidence moves a status. Evidence means a value read from the exchange or from the chain — a receipt, a subaccount snapshot, a settlement record. A transport error is not evidence: it means we do not know, not it did not happen.
Everything else in this section follows from that sentence. A failed RPC call never marks a withdrawal failed. A timeout never releases a reserve. A row that cannot be confirmed stays claimed and is retried, because the alternative — assuming the worst and rolling back — is how you pay twice.
The corollary is that almost every money path is resumable: it records what it is about to do, does it, then records the result, and every step is keyed so that repeating it is free.
How to read this section
| You want | Page |
|---|---|
| The module map, the schedulers, the advisory locks | Architecture |
| Accounts, events, posting rules, idempotency, projection, balances | Ledger and balances |
| How money enters: HD addresses, the bridge, sweep, subaccount creation | Deposit |
| Order → position → settlement, ITM and OTM | Positions and expiry |
| The swap on Base, the conversion circle after an ITM call | Conversion and swap |
| How money leaves: reserve, signing, delivery, gas | Withdrawal |
| The automated wheel and the external signal | Auto-wheel and signals |
| Comparing our ledger against the exchange | Reconciliation |
| SIWE login, JWT, HD index derivation | Auth and HD wallets |
| The showcase, spot prices, charts, the asset list | Market data |
| Subaccounts, fees, trading profiles, the Derive client, OpenAPI | Platform services |
| Places where the obvious search gives the wrong answer | Traps |
| Locks, accounts, event types, idempotency keys, env vars, HTTP surface | Reference tables |
| What has actually run with real money, and what has not | Where we actually are |
What this section is not
It is not a restatement of the specs. docs/superpowers/specs/ holds the design documents and the
*-how-it-works.md files, and they go deeper on individual decisions — including the measurements
behind them. This section carries what those files do not: the cross-cutting tables that exist in no
single spec, and the traps.
Several specs have drifted from the code. Where this section and a spec disagree, the code was read; the disagreements are named on the page that covers the area. See Traps.