How the simulation works, and how far to trust it.

The code is in frontend/src/sim/ (profiles.ts, analyze.ts, flow.ts, tests.ts). Each rule below is what that code does today; the numbers in this page are checked against it by a test.

1. 1.1 Load comes from traffic

   A use case with rate R splits its traffic over its scenarios by mix; without mix it all goes to the first scenario, and shares that do not add up to 100% are scaled. Every request step that gets through (-> and ->>) adds its rate to the node it targets. Responses add nothing, and neither does a failed call (-x): in that scenario its target is down, so it receives nothing and sends nothing back.

   Every step counts, also steps after the response and the work an async consumer does later, so a queue's consumer carries load even though the user never waits for it. A use case without a traffic line adds no load.

   load(n) = Σ  R(U) × share(s) × N(step)
             over every request step to n that is not -x
             in every scenario s of every use case
   
   N(step) = the x<N> fan-out, 1 without one

2. 1.2 Reads and writes

   Each request step is a write when its HTTP method is POST, PUT, PATCH or DELETE, or, without a method, when the first word of its label is a write verb: INSERT, UPDATE, UPSERT, DELETE, SET, PUBLISH, SEND, ENQUEUE, CHARGE, CREATE, SAVE, STORE, UPLOAD, RESERVE, HOLD and about thirty more (full list). Everything else (GET, SELECT, QUERY, SCAN, LOOKUP, an event name) is a read. A request to a queue is always a write, whatever its label.

   Reads and writes are counted separately against separate capacities, and only writes count for durable and writes X before responding.

   Write

   api -> db : INSERT order

   Write

   user -> api : POST /orders

   Write

   api ->> jobs : OrderPlaced queue

   Read

   api -> cache : GET feed:{user}

   Read

   api -> db : SELECT posts

3. 1.3 Replicas, shards and single-primary writes

   A node declared with x<n> has n replicas; capacity { db shards 4 } splits a store into independent partitions, each with its own replicas. Every replica of every shard is assumed to get an equal slice of the load.

   Relational databases (PostgreSQL, MySQL, Aurora, RDS, SQL Server, …) are single-primary: their replicas serve reads, but every write goes to the one primary of its shard, so replicas add read capacity and only shards add write capacity. Everything else, including partitioned NoSQL stores, caches and queues, serves reads and writes on every replica.

   A node's request utilisation is the busier side for a single-primary store (replicas and primaries work in parallel) and the sum of both shares for everything else (they share the same machines). Its utilisation is the larger of that and its bandwidth utilisation (1.6). At or above 100% the node is saturated: every latency requirement of a use case that sends it load fails. Above 70% it is shown as hot.

   read capacity  = reads × replicas × shards
   write capacity = writes × shards              single-primary
                  = writes × replicas × shards   everything else
   
   ρ_read  = read load  ÷ read capacity
   ρ_write = write load ÷ write capacity
   
   ρ_req = max(ρ_read, ρ_write)   single-primary
         = ρ_read + ρ_write       everything else
   
   ρ = max(ρ_req, ρ_bandwidth)

4. 1.4 Utilisation turns into queueing

   Each node has a base latency per call when idle (from its profile, below). Under load a request may wait for a free server. The model treats each replica of a shard as one server whose service time is that base latency, and uses the M/M/c queue: with c servers at utilisation ρ, a request waits with the Erlang C probability C, on average base ÷ (c(1 − ρ)). Load is spread evenly over shards and a key's requests can only go to its own shard, so c is one shard's replicas; writes that bind a single-primary store queue for its one primary.

   One server gives the classic 1 ÷ (1 − ρ) slowdown. A pool waits much less at the same utilisation: at 50%, one server waits half the time, four servers 17%. Utilisation is capped at 95% in this formula, so a saturated node has a finite latency (at most 20× its base) and fails its requirements through saturation instead.

   C      = Erlang C(c, ρ)              ρ capped at 0.95
   hop(n) = base + C × base ÷ (c (1 − ρ))
          = base ÷ (1 − ρ)                 for c = 1

   Slowdown over the idle latency by utilisation

   ρ	10%	50%	70%	90%	≥ 95%
   1 server	1.1×	2×	3.3×	10×	20×
   4 servers	1×	1.09×	1.36×	2.97×	5.46×

5. 1.5 Latency and percentiles

   A scenario's mean latency is the sum of the hops on the synchronous critical path of its entry request: requests sent before the entry request is answered, by the entry's sender or by a node still working on it synchronously. A par group counts its slowest member; an async send (->>) counts its own hop but not the receiver's work; a failed call (-x) costs a fixed timeout of 1000 ms instead of the target's latency, or what capacity { db timeout 200ms } sets for that node.

   Percentiles are computed, not measured. Each hop's time is a fixed part (half its service time) plus an exponential tail that carries the rest of its mean: the other half of the service time and all of the queueing. An idle hop's p99 is 2.8× its mean; one server at 50% makes it 3.7×, at 90% 4.4×. Timeouts and transfer time are fixed: they add once to every percentile. A path takes every hop at the same quantile, which errs on the slow side for long paths.

   A use case's percentile is the percentile of all its requests together: the scenarios mixed by their shares. With 10% cache misses, p99 is close to the miss path's p90; it moves smoothly as a share grows, without jumps. Both are solved numerically, the same way every time.

   item   = fixed + Exp(tail)
   fixed  = base ÷ 2 + transfer   (a -x: the timeout, no tail)
   tail   = hop(target) − base ÷ 2
   
   p_q(s) = Σ over the parts of the critical path of
              max over the items of the part of
                fixed + tail × ln(1 ÷ (1 − q))
   
   p_q(U) = the t with Σ share(s) × P(s ≤ t) = q

   Percentiles of an idle hop over its mean

   idle hop	p50	p90	p95	p99	p999
   ÷ mean	0.85×	1.65×	2×	2.8×	3.95×

6. 1.6 Fan-out, payload size, bandwidth and egress

   A label that starts with x200 means the step happens 200 times per request: load counts 200 calls; latency counts the step once (as if the calls were batched or parallel), but its 200 payloads all cross the link.

   A label with ~2MB gives the step a payload: a read's payload travels back from the node it asks, a write's goes from the sender. It adds transfer time at the slower of the two ends' per-replica bandwidth (client 10 MB/s, edge, CDN, load balancer and gateway 1,000 MB/s, service 200 MB/s, everything else 100 MB/s). The bytes also fill the bandwidth of the nodes you run: a service whose payloads exceed its replicas' bandwidth is saturated. Object storage and CDNs scale out behind one name, so for them bandwidth is only the speed of one transfer.

   Payloads sent to a client or a third party leave your network and are charged as internet egress by the node that sends them: $0.09/GB from anything you run, $0.02/GB from a CDN. Traffic between your own nodes (storage to a service, a CDN filling from storage) is free, and what clients and third parties send is not your bill.

   transfer(step) = N × size ÷ min(bandwidth(from), bandwidth(to))
   
   ρ_bandwidth(n) = payload bytes in and out per second
                    ÷ (bandwidth × replicas × shards)
   
   egress GB/month = R × share × N × size × 2,592,000 s ÷ 10⁹
                     for payloads sent to a client or a third party
   egress cost     = egress GB × price of the node that sends it

7. 1.7 Availability

   Each replica is up a fixed fraction of the time (profile below), independently of every other. A node is up when any of its replicas is. A use case is up when every node on the synchronous path of its main scenario (the one with the largest share) is up, except that a node with a fallback only takes the use case down when its fallback path is down too.

   A write to a single-primary store needs its primary. With a second replica, failover promotes one, but writes wait out the promotion: the model keeps 10% of the primary's downtime, so a PostgreSQL primary with replicas takes writes 99.995% of the time, alone 99.95%. Reads still count every replica.

   A fallback is a success scenario that calls the node with -x before the entry response and completes without a successful synchronous call to it. Load and saturation do not affect availability.

   A(n)       = 1 − (1 − a(n))^replicas
   A_write(n) = 1 − (1 − a(n)) × 0.1      single-primary, 2+ replicas
              = a(n)                      single-primary, 1 replica
   
   A(U) = Π over nodes n on the main path of
            A(n), or A_write(n) when the main path writes to it
            1 − (1 − A(n)) × (1 − A(fallback))     with a fallback

8. 1.8 Cost

   Each replica of each shard costs a flat monthly price from its profile, whatever its load, plus the egress above, for a 30-day month. Clients, DNS and external systems cost nothing. There are no instance sizes, tiers, reservations or per-request prices.

   cost = Σ over nodes  replicas × shards × cost(n) + egress cost(n)

9. 1.9 Failures: survive, fallbacks, single points of failure

   survive any node failure takes every node you run (not clients, external systems or DNS) and removes one instance. With two or more replicas, the whole design is analysed again with one replica fewer: the node must not saturate, and every latency requirement that held must still hold. On a sharded store the instance comes out of one shard; keys cannot move to another shard, so that shard's numbers are what count. A single-primary store that loses its primary promotes a replica: writes keep a primary and reads lose one replica, the same as losing a replica. With one replica, every use case whose success scenarios need the node must have a fallback scenario for it. survive failure of <selector> does the same for the selected nodes.

   The Analysis tab lists as single points of failure the single-replica nodes that some use case needs and has no fallback for. A failed call (-x) in a scenario is how a design says "and this is what happens when that node is down".

   x2+

   with one replica fewer, the node does not saturate and the latency limits still hold

   x1

   every use case that needs it has a fallback scenario

   Skipped

   clients, external systems, DNS, notes

10. 1.10 Tech stacks, kinds and consistency

    A node's tech stack picks its kind and its profile. The catalog knows 205 techs with the names people write as aliases ([S3], [Postgres], [ALB], [k8s]), ignoring case, punctuation and a trailing version. A tech it does not know is a warning, and the node is simulated as the kind its name suggests ([TigerBeetle DB] is a database), else the kind of the closest catalog tech, else a service: never a free, infinitely fast client.

    The edge splits into cdn, loadbalancer, gateway and dns, each with its own numbers; a firewall ([WAF]) is a plain edge, and any edge selects all of them. DNS is off the request path: it adds no latency, never fails and costs nothing. Every data store has a consistency, strong or eventual, used only by the selectors any strong store and any eventual store in tests; replication lag and staleness are not simulated.

    [Postgress]         did you mean PostgreSQL? → database
    [TigerBeetle DB]    unknown → database (from its name)
    [Cobol Mainframe]   unknown → service
    
    any edge            edge, cdn, loadbalancer, gateway, dns
    any strong store    relational, MongoDB, Spanner, queues …
    any eventual store  caches, DynamoDB, Cassandra, search, storage …

Default profiles, per replica

Teaching values, right to an order of magnitude, not benchmarks. capacity { … } overrides any of them per node (see How to read the results).

Relational databases take 5k writes per second per shard (on the primary), not per replica. Egress is the price of data a node sends to clients and third parties. A tech stack the catalog does not know gets the row of the kind its name suggests (a service when nothing does) and a warning that names the closest known tech; to keep a product name the catalog lacks without the warning, use the generic tech of its kind ([Database], [Message Queue]) and put the product in the node's name.

Every number in this section comes from running the simulation on the source shown next to it, and a test fails if the code and the page disagree. Paste a source into the editor to see the same numbers in its Analysis and Tests tabs.

title "Feed"

user  "User"       [Actor]
api   "Feed API"   [REST API]   x6
cache "Feed cache" [Redis]      x2
db    "Feed DB"    [PostgreSQL] x2

user -> api  : HTTPS
api -> cache : RESP
api -> db    : SQL

usecase "Read feed" {
  user -> api : GET /feed
  alt "Cache hit" {
    api  -> cache : GET feed:{user}
    api --> user  : 200
  } alt "Cache miss" {
    api  -> cache : GET feed:{user}
    api  -> db    : SELECT posts
    api  -> cache : SET feed:{user}
    api --> user  : 200
  }
}

usecase "Post" {
  user -> api  : POST /posts
  api  -> db   : INSERT post
  api --> user : 201
}

traffic {
  "Read feed" 6k rps mix "Cache hit" 90%, "Cache miss" 10%
  "Post"      1k rps
}

requirements {
  p99 "Read feed" < 60ms
  availability "Read feed" >= 99.9%
  durable "Post"
  survive any node failure
  cost <= 2500 usd/month
}

title "Orders"

client "Client"    [Actor]
api    "Order API" [REST API]   x8
db     "Orders DB" [PostgreSQL] x3

client -> api : HTTPS
api    -> db  : SQL

usecase "Place order" {
  client -> api    : POST /orders
  api    -> db     : INSERT order
  api   --> client : 201
}

traffic {
  "Place order" 6k rps
}

requirements {
  p99 "Place order" < 100ms
}

capacity {
  db shards 2
}

title "Photos through the API"

viewer "Viewer"    [Actor]
api    "Photo API" [REST API] x2
blobs  "Photos"    [AWS S3]   x2

usecase "View photo" {
  viewer -> api    : ~2MB GET /photos/{id}
  api    -> blobs  : ~2MB GET photo
  api   --> viewer : 200
}

traffic {
  "View photo" 20 rps
}

title "Photos through a CDN"

viewer "Viewer" [Actor]
cdn    "CDN"    [AWS CloudFront] x2
blobs  "Photos" [AWS S3]         x2

usecase "View photo" {
  viewer -> cdn : ~2MB GET /photos/{id}
  alt "Edge hit" {
    cdn --> viewer : 200
  } alt "Edge miss" {
    cdn   -> blobs  : ~2MB GET photo
    cdn  --> viewer : 200
  }
}

traffic {
  "View photo" 20 rps mix "Edge hit" 95%, "Edge miss" 5%
}

These follow directly from the formulas above. None of them changes which of two designs is better in ordinary cases, but each one moves absolute numbers in a known direction.

Most omissions make the model optimistic: real systems are slower, less available and dearer than the numbers say. Treat a design that only just passes as one that would fail.

1. 5.1 Compare designs, find the bottleneck

   The model is deterministic and its inputs are rough, so read its numbers relatively. Two designs under the same traffic and profiles compare fairly: a cache that takes p99 from 300 ms to 40 ms, a database that goes from 120% to 60%, a CDN that cuts egress by four. A 10% difference between two designs is inside the error of the teaching values.

   The utilisation column shows where the design gives out first. Raise the traffic until something turns amber (above 70%) or red (saturated): that node, and the lever the hint names (replicas, shards, a cache, async work), is what the design is really about.

   Do not size a fleet from these numbers or quote them as SLOs. A capacity plan needs load tests of your own services, your peak traffic and your cloud bill.

   Good for

   comparing designs, finding the first bottleneck, spotting single points of failure, sanity-checking a budget

   Not for

   capacity plans, SLO commitments, cost forecasts, tail-latency estimates

   Fixed

   no randomness, no warm-up: the same text always gives the same numbers

2. 5.2 Calibrate with your own measurements

   capacity { … } replaces any default for one node, per replica. Once you have real numbers, put them in and the rest of the model works from them:

   • Rate (3k rps, or reads … writes …): the throughput at which one replica stops keeping up in a load test, since the model adds queueing delay on top. Not the rate at which latency is still fine.
   • Latency: the median per call at low load, measured from the caller, so it includes the network.
   • Availability: per replica, from your provider's SLA or your incident history.
   • Cost: what one replica costs on your bill. Egress and bandwidth: your prices and your instance's network.
   • Shards, durable, consistency: how the store is actually set up.

   Calibrated rates fix the capacity side; the omissions in section 04 still apply, so keep headroom.

   capacity {
     api   3k rps latency 12ms cost 140 usd/month
     db    reads 25k rps writes 6k rps availability 99.95%
     users shards 4 consistency strong
     blobs bandwidth 500 MB/s egress 0.05 usd/GB
   }

1. 6.1 What "Solved" means

   A practice problem is solved when every requirement and every test in the problem's given file passes against your design, with the same simulation as the editor. The problem fixes the traffic, the limits and any capacity numbers; a capacity line in your own file is an error, except shards <n>, so you cannot buy your way out with a bigger node.

   Passing means the design is sound under this model: the requests flow the right way, nothing saturates at the given traffic with the default numbers, every node you run can fail without breaking a use case, and the bill fits the budget. It does not mean the system would hold up in production; section 04 is still true.

   Latency

   p99 limits fail when the path is too long, a node queues, or any node a use case loads is saturated

   Failure

   survive and availability fail on single points of failure

   Cost

   the budget fails designs that throw replicas at the problem

   Flow

   tests check the key idea: cache before database, write before responding, never wait for a queue

2. 6.2 Why brute force fails

   Each problem's limits are set between the reference solution and the shortcuts a candidate might try: loose enough that the intended design passes with room, tight enough that the shortcut does not. More replicas fix saturation but break the cost budget; skipping the cache saves its cost but loads the database and the p99; a load balancer in front of storage fails the flow test that asks for a CDN.

   Every problem keeps those shortcuts as wrong/*.proschi designs, each naming the tests it must fail. proschi problem check runs them in CI, so a change to the model or the limits that lets a shortcut pass is caught before it ships. How problems are calibrated.

   # expect-fail: p99 of Hold seat < 130 ms
   # Scales the relational database with read replicas instead of shards.
   import "problem.proschi"
   
   # … the rest of the design …
   db "Seats DB" [PostgreSQL] x4