Skip to content

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 ​

growsbites whenwhat to do
an instant kind's recordsthe startup snapshot gets heavy — every device loads all of itcheckSnapshotBudget 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 recordit will not: tracked updates send only the fields that changednothing; split a record only for identity reasons, never size
a collection without bound (messages, activity)it is never one value: many records, each its ownbelongsTo a lazy root, or a query with cursor pages; memory follows what is open, not what exists
streaming textresending it whole on every changeappendable: 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. instant records stay loaded; lazy and embedded ones 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 instant topic 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):

    ts
    rings: {
      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 to default for what it omits, and default and instant are reserved kind names (as is twinstate, 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's maxAge longer than its topic's ring age has no effect.

  • Compatibility. Which lock revisions the server can serve is computed once at startup; a hello is one lookup, and nothing is checked per message.

  • Listing. An instant kind 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; the instant topic 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 as z.ZodType<T>: that erases its input type (zod 4 defaults it to unknown), 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')), and client.preload would 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:

dimensionbites whenwhat to do
writes (about a thousand short turns a second)slow handlers; a store write per turnhandlers stay short, long work is a job; a faster store write; past that, partition
fan-outserializing each flush per connection, more with per-viewer projectionserialize once per topic and projection, shared by equal contexts; then relays (below)
a slow clientits send buffer growsa capped buffer per connection: past it, the client's topics are dropped and it resets later, never buffered forever
data in memorya big instant kindinstant kinds stay small; the rest is lazy, read through windows

Across partitions:

dimensionbites whenwhat to do
placementmany partitions to placethe load balancer routes by partition (below)
cold startsloading a partition's instant dataactivate a partition on its first connection; evict it when idle
deploysevery 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
failoverone owner per partitiona lock per partition, with fencing in the store (below); recovery takes a cold start
one crowded partitionfan-out to many viewersrelays: 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:

  1. one server instance is one partition, with no module-level state; a process may run many;
  2. a turn belongs to one partition;
  3. the change log is an ordered, serializable stream (epoch, revision, ops), and projection per viewer happens after it, so relays can project too;
  4. 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;
  5. each connection's send buffer is capped, and dropping a client means it resets, which is always correct;
  6. the partition is known when a connection opens;
  7. handlers are short, and long work is a job;
  8. 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:

piecehowwho
routingthe load balancer hashes on the partition id (Envoy, HAProxy, nginx, an ingress), so a partition's connections land on one podinfrastructure
activationeach 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 appliedyour app
one owner at a timea lock per partition (a Redis lock, a Postgres advisory lock, a Kubernetes Lease), with fencing in the storeinfrastructure and your store
drainingserver.close() finishes the queue and closes the sockets, at onceTwinstate
the server's outboxa 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 streamTwinstate'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 ─ exit

On 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:

raceprevented by
two processes both owning Pthe lock and fencing: the store refuses a write carrying an old token
a result sent while P has no ownerthe 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 PTwinstate 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 codemutation arguments follow the lock file's compatibility rules, as for an older client
a webhook landing on a pod that does not run Pthe 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 touchwrite load on one queue
documentone documentsmall
usereverything of that userone person's activity
workspace or teameverything the team sharesthe whole team's activity
the whole appeverythingeveryone'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.

directionpatternhow
ina 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
inmessage queues (Kafka, NATS, SQS), webhooks, schedulerseach message or call is a mutation with its id as key, so a redelivery applies once
injob queues and worker fleets (pg-boss, AI calls, transcoding)workers report with mutations on a job's record (async work)
outsearch indexes, warehouses, audit logsa consumer reads server.changes(from), the ordered change feed, resuming from its position
outpublish exactly when a turn commitswrite an outbox row in the turn's store transaction (dbTx); a relay publishes it
outpush notifications, emailserver.onEvent, or the change feed
aroundpublic reads that need no live connectionserver-rendered or CDN-cached pages built from server.get
aroundblobsobject storage with presigned uploads; records hold the URL
aroundstorage per partitiona SQLite file per partition (LiteFS, Litestream, Turso)
aroundpresence, co-edited text, analyticsa 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.

storeholdswritten by
the ledgeraccounts, double-entry transfers, idempotency keysthe ledger service, in transactions
the app's databasepayees, preferences, Twinstate's own recordsTwinstate's adapters
a read model (optional)balances and recent transactions per userthe 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.

storeholdsread and written by
sharded by user (Vitess, Citus)profiles, settings, posts by author, follows, notificationshome partitions' adapters, each on its user's shard
sharded by postcomments, reactionsthread partitions' adapters
a timeline store (Redis, Cassandra)each user's feedwritten by a fan-out service; read by the home partition's feed window
a counter servicelikes, followersbridged into thread partitions periodically
searchpostsfed 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 ​

sourcethe lesson
How Figma's multiplayer technology worksa process per document, writes ordered by the server, last write wins per property: this model, at scale
Slack: real-time messaginggateways 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 serverfan-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 usersa process per guild, and a session process per connection: partitions by community
Rules of Durable Objectsone object per room, user or document, at roughly 500–1,000 requests a second each
Scaling the Linear Sync Enginewhat breaks as a sync engine's data grows, and when to load it into memory
Zero: self-hostingone writer feeding many read nodes
Designing Data-Intensive Applications (Kleppmann)partitioning, replication and change streams as derived data

Sources ​