Scalability
What grows as an application does, what bites first, and what to do about it. One Twinstate server is one partition: one ordered queue, its records and its topics, serving from a handful to many hundreds of clients (to be measured). An application grows past one by running many, across machines (scaling out); the sections before that say where one partition holds and where it stops.
Data
| grows | bites when | what to do |
|---|---|---|
an instant kind's records | the startup snapshot gets heavy — every device loads all of it | checkSnapshotBudget fails first. Split the kind into an instant summary and a lazy detail sharing an id, or make it lazy and read it through a query |
| one record | it will not: tracked updates send only the fields that changed | nothing; split a record only for identity reasons, never size |
| a collection without bound (messages, activity) | it is never one value: many records, each its own | belongsTo a lazy root, or a query with cursor pages; memory follows what is open, not what exists |
| streaming text | resending it whole on every change | appendable: only the suffix travels |
The rule underneath: cost grows with changes, not with data. A flush sends the patches recorded since the last one and compares nothing; a snapshot is the one full read, and it is bounded by the budget.
The server
One queue per partition. A turn takes milliseconds when handlers do a short durable write, so a handful of devices never notice the others. Durable Objects serve around a thousand requests a second per object this way. What one queue cannot absorb is a slow handler — the kit fails any over 100ms. If one queue is ever measurably too slow, the answer is a coarse partition (one queue per natural unit, like Replicache's "spaces"), never per-record locking, and never batching turns within a partition (why).
Memory.
instantrecords stay loaded;lazyandembeddedones are loaded when a topic needs them and evicted when none does. So memory follows the number of open screens across all clients, not the size of the data.Rings. Each topic keeps its recent changes for replay: by default its last 1,000, at most 1MB and at most ten minutes old, whichever comes first. A change is typically 100–300 bytes (a streamed chunk tens), so a full ring is about 200KB. Memory is per topic, not per client: a ring holds each change once and projects it for each viewer when sending, so a topic's watchers share it, and an idle topic's ring is nearly empty. A partition holding its
instanttopic and ten open roots needs at most a couple of megabytes for rings. A client away longer than a topic's ring resets that topic (one snapshot of it), which is correct, just heavier; the others still resume. Only a restart (a new epoch) or a changed context resets every topic a client holds. Rings are tuned in one place (designed):tsrings: { default: { entries: 1000, bytes: '1MB', age: '10m' }, // every topic instant: { entries: 5000 }, // the instant topic, which carries everyone's activity reply: { entries: 5000, age: '30m' }, // a lazy kind's topics: streaming replies },The keys are typed (
default,instant, and lazy kinds' names, so a typo does not compile), an override falls back todefaultfor what it omits, anddefaultandinstantare reserved kind names (as istwinstate, the name of Twinstate's own records). When snapshots grow large, a reset can send only what differs from what the client holds, from bucketed hashes it sends up (see resuming after a disconnect).Events live in the topic rings with the changes, so they add nothing of their own to memory; replaying them stops at whichever comes first: the ring's own bounds (entries, size, age) or the event's
maxAge, so an event'smaxAgelonger than its topic's ring age has no effect.Compatibility. Which lock revisions the server can serve is computed once at startup; a
hellois one lookup, and nothing is checked per message.Listing. An
instantkind is listed in full for every snapshot — the price of "every record on every device". A queried kind is listed one window at a time, which a database answers from an index.Twinstate's own records. One short record per client ever seen (every tab is a client, so even a single-user app has many), and a mutation turn rewrites only its own client's row, so its cost stays the same however many clients there have been. Retiring empty outboxes removes them; a client's record is never dropped by age (a held entry must still be recognised when released). Keys of server mutations are dropped after
keyRetention.
Clients
- One socket per tab. Tabs never share live state, which keeps the multi-tab design simple; the cost is a connection each, fine for one person's tabs and something to revisit only at many tabs per user.
- The persisted cache is bounded by
maxBytes: other versions' topics go first, then lazy topics least recently opened; theinstanttopic stays. - Pending effects are re-applied on every replica change, so their cost is (pending mutations) × (changes). Both are small in practice; the effect benchmark keeps it so.
Type-checking time
Types cost nothing at run time — they are erased — but a large registry is a lot of inference for the compiler, and zod's types used to be the slow part: zod 3 could produce tens of thousands of type instantiations for one complex schema. Zod 4 redesigned its generics and reports about 175 for the same file, and teams upgrading report tsc falling from ~47s to ~5s. Twinstate requires zod 4. If type-checking still slows:
- give a big kind its own module and export its record's type once (
type Note = z.output<typeof note.schema>), so dependents reuse a named type instead of re-inferring the fields. Do not annotate a field's schema asz.ZodType<T>: that erases its input type (zod 4 defaults it tounknown), which the JSON, defaults and argument checks all depend on; - keep registry modules small and imported, not one giant file, so editors re-check less on each change.
Bundle size
Every client ships every kind's schema and every mutation's effect. At a few dozen kinds that is small (a whole client of that size can be ~100KB gzipped). Past that, the common practice is route-level code splitting: a shell loads up front, and each screen's code arrives as it is opened — React Router's lazy route modules and TanStack Router's automatic code splitting both fetch a route's code in parallel with its data.
Twinstate can grow into this without a redesign, as per-kind splitting (on the roadmap, not built):
- the wire names kinds, so a client needs a kind's schema and effects only once one of its topics arrives or one of its mutations runs;
- a registry entry could be
lazyKind(() => import('./noteBody')), andclient.preloadwould fetch that chunk alongside the data, the way React Router's loaders overlap code and data.
Two constraints would stay: instant kinds — and anything they ref — are in the main bundle, because the snapshot needs them at startup; and a bundle's lock revision is fixed at build time over every kind, split or not, so a client knows what it can read before any chunk loads. Splitting also brings one hosting duty: a tab opened before a deploy may fetch a kind's chunk after it, so the host must keep the previous build's chunks for a while (deleting them is the usual cause of "failed to fetch dynamically imported module" after a deploy).
Scaling out
Designed, not built or measured. Twinstate scales to many servers the way every engine of its kind does (comparison): by partitions. Each createTwinServer instance is one partition, with its own queue; an application runs as many as it needs, spread across machines, and places and routes them as it likes (a gateway with consistent hashing, or a platform such as Durable Objects). Figma runs a process per file, Discord one per guild, Slack channel servers behind gateways.
The condition: the data divides into units (a user, a team, a document, a community), and a turn stays inside one. Ordering is already per partition and by arrival, so splitting costs nothing within a unit, only between units. Two shapes do not scale this way, in Twinstate or any engine like it:
- one shared unit with heavy writes (every player writing one leaderboard each second): reads scale through relays, its writes do not. Model it instead: each player's score in their own partition, an aggregator sending the top N periodically, as Cloudflare's sharded counters do.
- transactions across many units: they become sagas (below).
Within one partition:
| dimension | bites when | what to do |
|---|---|---|
| writes (about a thousand short turns a second) | slow handlers; a store write per turn | handlers stay short, long work is a job; a faster store write; past that, partition |
| fan-out | serializing each flush per connection, more with per-viewer projection | serialize once per topic and projection, shared by equal contexts; then relays (below) |
| a slow client | its send buffer grows | a capped buffer per connection: past it, the client's topics are dropped and it resets later, never buffered forever |
| data in memory | a big instant kind | instant kinds stay small; the rest is lazy, read through windows |
Across partitions:
| dimension | bites when | what to do |
|---|---|---|
| placement | many partitions to place | the load balancer routes by partition (below) |
| cold starts | loading a partition's instant data | activate a partition on its first connection; evict it when idle |
| deploys | every client resets every topic at once (a new epoch) | the snapshot budget and windows bound each reset; jittered reconnects; resets that send only what differs |
| failover | one owner per partition | a lock per partition, with fencing in the store (below); recovery takes a cold start |
| one crowded partition | fan-out to many viewers | relays: followers consume the partition's change stream, project for their own connections, and forward mutations to it (Discord's relays, Zero's view-syncers) |
Partitions talk the way Durable Objects do: by messages, never inside a turn. A turn never awaits another partition (it would stall its queue, and two waiting on each other would deadlock): it commits, then sends from afterEveryCommit, and the receiver applies the message as its own turn, a mutation sent with a key (server.mutate(m, args, { key })), so a retry applies it once. Multi-step work across partitions is a job whose record tracks its steps (a saga), and clients may see its middle (a document marked "moving").
The client is always one Twinstate (one client, replica, outbox, provider). When its topics live in several partitions, a gateway routes each to its own, as Slack's and Discord's gateways do: the protocol addresses a topic as (partition, topic), which a single-partition app never sees.
Rules the server keeps, so scaling stays possible:
- one server instance is one partition, with no module-level state; a process may run many;
- a turn belongs to one partition;
- the change log is an ordered, serializable stream (epoch, revision, ops), and projection per viewer happens after it, so relays can project too;
- nothing in memory crosses processes: a partition started elsewhere starts a new epoch from the store, and memory-only state is derived or the current process's activity;
- each connection's send buffer is capped, and dropping a client means it resets, which is always correct;
- the partition is known when a connection opens;
- handlers are short, and long work is a job;
- applying a turn in memory, persisting it and publishing it stay separate steps of the turn pipeline, so each can change on its own: a relay publishing, a store grouping commits across partitions (the transaction).
Running on many machines
Designed, not built. On interchangeable machines (a Kubernetes Deployment, where pods are added and removed in any order and rolling updates overlap old and new), a partition still runs on one machine at a time. Most of what that takes is standard infrastructure; Twinstate's own share is small. Who does what:
| piece | how | who |
|---|---|---|
| routing | the load balancer hashes on the partition id (Envoy, HAProxy, nginx, an ingress), so a partition's connections land on one pod | infrastructure |
| activation | each pod keeps a map of the partitions it runs, and creates a server for one on its first connection, or when outbox.watch reports mutations saved for one the hash assigns it, so a webhook for someone offline is still applied | your app |
| one owner at a time | a lock per partition (a Redis lock, a Postgres advisory lock, a Kubernetes Lease), with fencing in the store | infrastructure and your store |
| draining | server.close() finishes the queue and closes the sockets, at once | Twinstate |
| the server's outbox | a result sent with server.mutate after its partition moved is saved, and applied by whichever process starts the partition: a table with LISTEN/NOTIFY, a Redis stream | Twinstate's interface, an adapter you pick |
phones / browsers (each connection carries its partition: a user or workspace id)
│ WebSocket
▼
┌────────────────────────────────────┐
│ load balancer, hashing on the │ [infra] the same id always lands on the same pod
│ partition id │
└────────────────────────────────────┘
│ P1,P3 │ P2,P4 │ P5
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│ pod A │ │ pod B │ │ pod C │ [app] each pod's map: id → createTwinServer(...)
│ P1 P3 │ │ P2 P4 │ │ P5 │
└────────┘ └────────┘ └────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────┐
│ locks: P1 P2 P3 P4 P5 held │ [infra] one owner per partition
│ outbox: mutations saved for their owner │ [adapter] a table or a stream
│ your data (a fencing token on every write) │ [store]
└──────────────────────────────────────────────┘A first connection to a partition no pod runs: the pod takes its lock and creates its server, which starts a new epoch from the store, so clients reset — the same path as any restart. Nothing is carried from the previous owner: a reset re-sends from the store, which stays right whatever happened to the store in between (see design notes).
A pod stopped (a deploy, scaling down): on SIGTERM,
ts
draining = true; // the pod's activation starts no more partitions, for connections or saved mutations
stopWatching(); // the function outbox.watch returned
const running = [...partitions]; // the pod's map of the partitions it runs
await Promise.all(
running.map(async ([id, server]) => {
await server.close(); // ~1s, all at once: no waiting on follow-up work
await lock.release(id); // another pod may take the partition now
}),
);
await myWork.finish(25_000); // the app's own async work; what it reports now is saved in the outbox
process.exit(0);The load balancer sends those partitions elsewhere, and whichever pod gets one next starts it.
Follow-up work that outlives its partition's move keeps running on the old pod, which serves no one any more. Its result is a mutation — data, not code — so it can be applied wherever the partition now is: server.mutate sees the partition is closed here and saves the mutation in the server's outbox, where it stays until the new owner takes it. That is Akka's sharding ("incoming messages will be buffered … delivered to a new incarnation of the entity") and Discord's backlog after a guild handoff, kept durably:
0s pod A: SIGTERM ─ close() ─ release P (~1s)
1s pod B: take P ─ start (new epoch) ─ take from the outbox ─ clients reconnect
pod B serves everyone from here; new work starts on B
pod A: charge #101 ·········· 20s done ─► server.mutate ─► closed here ─► outbox ─► pod B applies it (its key)
20s pod A: its own work done ─ exitOn one server the server's outbox needs nothing: it is kept in Twinstate's own records and read when the partition starts. On several machines it is three functions, the size of a store adapter, because the process saving into it has lost the partition's lock (a fenced store would refuse it) and the new owner is already running (Socket.IO splits its adapters the same way: in memory by default, Redis or Postgres for several servers):
ts
outbox: {
// called by Twinstate, per partition:
save(partition, mutation), // a mutation for a partition that is not in this process: stored durably
take(partition, onMutation), // this process has started the partition: hands over what is saved now, and
// whatever is saved later, until the returned stop function is called
// called by your pod's activation code, once per pod:
watch(onWaiting), // mutations are saved for a partition nobody runs: start it if the hash assigns it here
}The races of two processes overlapping, and what prevents each:
| race | prevented by |
|---|---|
| two processes both owning P | the lock and fencing: the store refuses a write carrying an old token |
| a result sent while P has no owner | the outbox keeps it until an owner takes P (an outbox kept only in memory loses it: the crash case) |
| a result reaching the new owner before it has started P | Twinstate takes from the outbox only after the partition has started |
| the same result sent twice (the old pod, and a webhook) | the key: applied once |
| a result sent by old code, applied by new code | mutation arguments follow the lock file's compatibility rules, as for an older client |
| a webhook landing on a pod that does not run P | the pod has no server for P, so it saves straight into the outbox: saveToOutbox(outbox, P, m, args, { key }), the same mutation server.mutate would save |
A pod crashed: its locks expire after a few seconds, the next connection starts the partition elsewhere, and clients reset. Work the pod was running is the crash case of async work.
Fencing: a lock carries a token, and every write carries it, so a pod that lost its lock (a long pause, a network split) and wakes still believing it owns the partition has its writes refused by the store. The token is yours: your adapters are created with it, and the store checks it, which is what prevents two pods writing one partition. Twinstate does nothing here.
Rolling updates and scaling up: a new pod cannot run a partition while another holds its lock. When a pod is added, the hash moves some partitions to it while their old pods still hold them; the new pod then asks the owner to hand the partition over (a release request through the lock store, as Akka's shard handoff does), and the connection waits about a second: the owner closes and releases, and the new pod starts it. The handoff never waits on follow-up work — Discord's voice outage of March 2026 began when "a safety check designed to wait for other events in progress to complete meant the termination grace period in Kubernetes elapsed before handoffs could begin". The request and the wait are part of the recipe, not of Twinstate.
On Durable Objects, the platform does routing, activation and single ownership, so each partition is one object and none of the above is yours: server.mutate from a Worker, a Queue or a Workflow is a call on the object's stub.
Serverless functions are out by design: a partition is a long-lived process holding its queue, rings and connections, which short-lived functions cannot be.
Choosing the partition is the first decision: a turn can touch anything in one partition, atomically, and nothing in two.
| a partition per… | one turn can touch | write load on one queue |
|---|---|---|
| document | one document | small |
| user | everything of that user | one person's activity |
| workspace or team | everything the team shares | the whole team's activity |
| the whole app | everything | everyone's: one server, no scaling out |
How this will be proven: several partitions in one process behind a stub router in the test kit from the start (a handoff in the middle of every follow-up included), and three benchmarks once the server exists: turns per second for one partition with a real store, fan-out to N connections with projection, and a reconnect storm after a restart.
Building on Twinstate
What others build around Twinstate scales an application as much as Twinstate itself does. External systems never write behind its back: they write throughserver.mutate, with a declared mutation.
| direction | pattern | how |
|---|---|---|
| in | a database's change log (Postgres logical replication, Debezium) | a bridge sends each change as a mutation, with the change's position as key; adapters upsert |
| in | message queues (Kafka, NATS, SQS), webhooks, schedulers | each message or call is a mutation with its id as key, so a redelivery applies once |
| in | job queues and worker fleets (pg-boss, AI calls, transcoding) | workers report with mutations on a job's record (async work) |
| out | search indexes, warehouses, audit logs | a consumer reads server.changes(from), the ordered change feed, resuming from its position |
| out | publish exactly when a turn commits | write an outbox row in the turn's store transaction (dbTx); a relay publishes it |
| out | push notifications, email | server.onEvent, or the change feed |
| around | public reads that need no live connection | server-rendered or CDN-cached pages built from server.get |
| around | blobs | object storage with presigned uploads; records hold the URL |
| around | storage per partition | a SQLite file per partition (LiteFS, Litestream, Turso) |
| around | presence, co-edited text, analytics | a presence service, a Yjs server, a warehouse fed by the change feed |
Three hooks make these safe, designed, not built: server.mutate(m, args, { key }), applied at most once per key; server.changes(from), an ordered, resumable change feed; and store adapters that upsert.
Worked examples
A personal assistant. One partition per user; Twinstate is the backend: the user's conversations, settings, files and agents, with their jobs and streamed replies, in their own queue, stored in their own files or database file.
Banking. One partition per user as the live view; a ledger database (Postgres, or a dedicated ledger) is the truth.
| store | holds | written by |
|---|---|---|
| the ledger | accounts, double-entry transfers, idempotency keys | the ledger service, in transactions |
| the app's database | payees, preferences, Twinstate's own records | Twinstate's adapters |
| a read model (optional) | balances and recent transactions per user | the bridge, through upserting adapters |
requestTransfer leaves the outbox as an intent. Its handler only records it, a transfer with status pending, whose adapter enqueues the ledger call in the same transaction (a durable job, keyed by the transfer's id as the ledger's idempotency key; see async work), so a slow ledger never holds the user's queue and a crash never loses a transfer. The ledger's entry is bridged into both users' partitions ({ key: entryId }), marking the transfer done. The sender sees "pending" until then, never a balance the ledger may still refuse.
A social network. A home partition per user, and one per thread or community; the stores are sharded.
| store | holds | read and written by |
|---|---|---|
| sharded by user (Vitess, Citus) | profiles, settings, posts by author, follows, notifications | home partitions' adapters, each on its user's shard |
| sharded by post | comments, reactions | thread partitions' adapters |
| a timeline store (Redis, Cassandra) | each user's feed | written by a fan-out service; read by the home partition's feed window |
| a counter service | likes, followers | bridged into thread partitions periodically |
| search | posts | fed by the change feed |
A new post is written to its author's shard; after its turn commits, the fan-out service writes timeline entries and, for followers online, sends a new feed item (a mutation) to their home partitions, so it appears live. Partitions are working sets over these stores, never the stores themselves.
Further reading
| source | the lesson |
|---|---|
| How Figma's multiplayer technology works | a process per document, writes ordered by the server, last write wins per property: this model, at scale |
| Slack: real-time messaging | gateways hold the sockets, channel servers hold the state, placed by consistent hashing |
| Discord: pushing Discord's limits with a million+ online users in a single server | fan-out, not writes, is the bottleneck; relays "are responsible for doing fanout with permission checks", up to 15,000 sessions each |
| Discord: how Discord scaled Elixir to 5,000,000 concurrent users | a process per guild, and a session process per connection: partitions by community |
| Rules of Durable Objects | one object per room, user or document, at roughly 500–1,000 requests a second each |
| Scaling the Linear Sync Engine | what breaks as a sync engine's data grows, and when to load it into memory |
| Zero: self-hosting | one writer feeding many read nodes |
| Designing Data-Intensive Applications (Kleppmann) | partitioning, replication and change streams as derived data |