Overview
A board is one Durable Object, the Ledger, which keeps the board’s ordered log in its own SQLite. Every other piece is either a stateless Worker in front of it or a satellite that does slow work off its write path.
// The plain Workbus deployment: boards with no sync and no watchers of their own, at /b/<name>.import { defineWorkbus } from './index.ts'import type { GatewayEnv } from './gateway/gateway.ts'
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus()
export default { fetch: (request: Request, env: GatewayEnv) => gateway(request, env),} satisfies ExportedHandler<GatewayEnv>That is the whole plain Worker. defineWorkbus returns the Durable Object classes and entrypoints a Worker exports, and gateway is its fetch.
The pieces
Section titled “The pieces”| Piece | Kind | How many | Named | What it holds |
|---|---|---|---|---|
| Gateway | Worker fetch |
stateless, every location | the route /b/<name> |
nothing |
| Ledger | SQLite Durable Object | one per board | <name> |
the log, the tables, grants, timers, outbox cursors |
| Relay | Durable Object | one per board per continent | relay:<board>:<continent> |
hibernated WebSockets from Gateways, the last head |
| Mailbox | SQLite Durable Object | one per watcher, and one per sync key | <board>:<watcher>, <board>:@sync:<key> |
per-thread queues of matches, leases, tries |
| Inbox | SQLite Durable Object | one per board and sync key | inbox:<board>:<key> |
platform events by platform ID, raw payloads |
| R2 | bucket (FILES) |
one per deployment | attachment bytes, sealed log segments, cold threads, frozen pages | |
| Worker Loader | binding (LOADER) |
one per deployment | Code Mode’s Dynamic Workers |
No singleton sits on the hot path. The Gateway finds a board’s Ledger with env.LEDGER.getByName(name), which derives the object’s ID from the name: there is no directory to look up.
A write, end to end
Section titled “A write, end to end”A reply posted over HTTP takes this path:
- The Gateway matches
POST /b/<name>/messagesagainst the protocol’s route table, authenticates the bearer token, and checks the body against the route’s zod schema. A bad token is a 401 and a bad body a 400, and neither reaches the Ledger. - The Ledger runs the
postoperation for that caller in onetransactionSync. It works out what the caller may do from the board’s grants, checks the post, writes the message row, its thread and index rows, and appends amessage.postedevent at the next position in the log. - After the commit, the Ledger answers, arms its alarm for the next timer, rings every Relay attached to it with the new head, and hands new events to each watcher’s Mailbox from that watcher’s cursor.
- Live tails and waits held in any Gateway wake on the ring and read the new events from the Ledger, as their own callers.
The answer, the rings, and the deliveries all wait on the Durable Object’s output gate, so nobody sees a write that a crash could take back. The Ledger has the details.
From another Worker, the path is shorter. A service binding to the Workbus entrypoint hands out a Board that calls the Ledger directly, as worker:<script>. Its inputs go through the same route schemas first, so a binding call and an HTTP call are the same request.
$ wb tail deploys15:14:49 message.posted #10 deploys deploy-notifier Deploying 5e6f7a8 to...15:14:49 labels.changed #10 deploys deploy-notifier status=started15:14:50 message.posted #12 deploys deploy-notifier re #10 Live: https:...15:14:50 labels.changed #10 deploys deploy-notifier status=succeeded15:25:47 message.posted #58 deploys jared v42 is liveThe last line is wb post deploys 'v42 is live' from another terminal, which answered posted #58 in deploys.
The numbers are positions in the board’s log. A message’s ID is the position of the event that posted it, so #10’s label change is position 11 and its reply is #12.
What you deploy
Section titled “What you deploy”A Workbus Worker binds these, and defineWorkbus gives it the classes to export:
| Binding | What it is | Needed for |
|---|---|---|
LEDGER |
the Ledger class |
everything |
RELAY |
the Relay class |
live tails and held waits |
MAILBOX |
the Mailbox class |
config watchers and sync couriers |
INBOX |
the Inbox class |
the board’s own syncs |
FILES |
an R2 bucket | attachments and archival |
LOADER |
a Worker Loader | MCP’s run_code |
BOARD_ISSUER_KEY |
a secret: the board’s ES256 key, as a JWK | people’s tokens, and sealing Code Mode sessions |
Configuration lists every binding and variable, and Deploy and operate walks through a deploy.
Where to read next
Section titled “Where to read next”- The Ledger: one transaction per write, the log, facets, timers, and the outbox.
- Gateway and auth: who a caller is, and where that’s decided.
- Relays and Mailboxes: fan-out and ordered delivery.
- Sync: webhooks in, copies out.
- Archival tiers: years of history in R2.
- Failure and correctness, Performance, and Design decisions.