Architecture

NestJS 11 + TypeORM + Postgres. Dev port 4000, Swagger on /docs. Money is decimal.js through common/money.ts and never number. Schema changes go through migrations only — synchronize is off.

Module map

Counts are every .ts in the module including subdirectories and tests, recounted 2026-09-13.

Specs live in docs/superpowers/specs/auto-wheel/, except the two marked † — those are dated design documents one level up, in docs/superpowers/specs/. The index of all of them is docs/README.md.

Everything is a tick

There is no request that moves money. Every HTTP endpoint that starts a money movement answers 202 and writes a row; a background tick picks the row up. POST /positions, POST /subaccounts/:asset/release and POST /withdrawals all behave this way.

This is what makes the system resumable. A tick that dies halfway leaves a row in a claimed state with whatever evidence it had already gathered, and the next tick continues from there — rather than a request dying halfway and taking the only copy of the intent with it.

Advisory locks

One process must not run the same tick twice, and two processes must not run it at once. Each scheduler takes a Postgres advisory lock.

Three properties of these keys are deliberate and easy to break.

They are written as explicit numeric literals, never as arithmetic over an imported base. A collision introduced by a branch merge has to be visible to the eye in a diff.

The lock is session-scoped. It is taken on a dedicated createQueryRunner() and released on that same runner before release(). Take it on one connection and unlock on another and the unlock returns false while the lock stays held until the process restarts — a class of hang that looks like “the scheduler just stopped”.

The keys must differ. An advisory lock is global to the database, not scoped to a table. One shared key would make independent ticks queue behind each other while protecting nothing.

…005 is the only blocking one. Skipping a send is not an option there: two schedulers send from that address, both take nonce: 'pending', and if they overlap the second transaction evicts the first from the mempool — after the first has already had its hash recorded.

Claiming rows

Within a tick, rows are claimed with FOR UPDATE SKIP LOCKED, and the claim is an UPDATE wrapped in a CTE.

Rules that hold everywhere

• Money is Decimal only, through common/money.ts. Money.of takes a string; a number loses precision. Cross-currency arithmetic is blocked by assertSameCurrency.
• Fee rates and instrument limits are read from the live ticker at runtime (finding F17). Three separate Derive documentation sources contradict each other and the live values.
• Collateral is one-to-one (P7) — a product definition, not a margin consequence. Measured: PM2 would have allowed a call on 0.5 ETH against 0.2 ETH of collateral.
• An unknown error defaults to fatal and stops the subaccount, not the system.
• An unrecognised exchange operation status is never terminal. Calling it success posts money that may not exist; calling it failure abandons an operation that is still running.
• No step holds a lock across an external wait. The 20-minute maker window is a deadline_at column, not a held lock.
• Funds stay on the subaccount after settlement (P1), whatever the outcome. There is no automatic return.

How to check your work

pnpm --filter=@arkada/api typecheck
pnpm --filter=@arkada/api test src/<path>.spec.ts
pnpm --filter=@arkada/api test:integration          # needs Postgres

Live spending is behind a single switch, ALLOW_LIVE_SPEND=yes. Without it those tests skip rather than fail.