The Retry Storm example at 100 requests a second. The database is 99.9% busy and goodput is zero, because retries have turned 100 offered requests into 348 hitting a database that was already full.
Breakscale lets you put load balancers, caches, databases, queues and 29 other components on a canvas, wire them into a system, and drag the traffic up until something gives. What you see while it happens is a real discrete-event simulation: latency percentiles climbing, queues filling, circuit breakers tripping, and whole systems collapsing into retry storms, all measured from individual simulated requests rather than drawn to look plausible.
It runs in your browser, inside VS Code, and inside your AI assistant, which can read your code, draw your architecture, and tell you where it breaks.
Most system design material is static diagrams and rules of thumb. "Add a cache." "Use a queue." That makes it hard to build any intuition for why p99 latency falls off a cliff once utilisation passes 80 percent, or how a short timeout with a couple of retries turns one slow database into a total outage.
Breakscale runs the experiment instead of describing it. Load the Retry Storm example, drag the traffic up, and watch goodput fall to zero while the database is still working flat out, because every request it finishes has already been abandoned by a caller that gave up waiting.
Open breakscale.tech, pick an example from the left, and raise the traffic slider until something turns red. There is no account to make. A design stays in your browser unless you share it, and a shared design is encrypted before it leaves, with the key kept in the part of the link that browsers never send to a server.
Install Breakscale from the Marketplace
and run Open Breakscale from the command palette. The whole simulator opens in a panel beside
your code, with the same engine and examples as the website, and it works offline. Designs you
save there live in VS Code's own storage; a share link or a .breakscale file moves one between
the editor and the website.
Breakscale is also an MCP server, so Claude, Copilot, Cursor, Codex and other assistants can use it for you. Point one at a repo and ask it to turn the architecture into a design, or just describe a system, and it builds the design, runs it through the same engine, and comes back with measured numbers and a breakscale.tech link that opens it.
The server is hosted at https://mcp.breakscale.tech/mcp, so there is nothing to install. In
claude.ai, add that URL under Customize > Connectors > Add custom connector. Elsewhere:
# Claude Code
claude mcp add --transport http --scope user breakscale https://mcp.breakscale.tech/mcp
# VS Code
code --add-mcp '{"name":"breakscale","type":"http","url":"https://mcp.breakscale.tech/mcp"}'To run it on your own machine instead, any assistant can start npx -y breakscale-mcp --stdio
with Node 20. In assistants that support
MCP Apps, such as claude.ai, VS Code and
Cursor, the design also opens as a live canvas right in the chat, and anything you change there
goes back to the assistant, so its next edit starts from what you are looking at. The
MCP guide has setup for every client and some prompts worth trying.
A few things to ask once it is connected:
- "Read this repo and turn its architecture into a Breakscale design. Tell me which numbers you guessed."
- "Design a URL shortener that handles 2,000 requests a second, and show me where it breaks."
- "Double the traffic. What fails first, and how would you fix it without adding servers?"
- 33 components. Load balancers, caches, databases, queues and workers, plus CDNs, rate limiters, circuit breakers, read replicas, shards, autoscalers, stream brokers, WebSocket gateways, serverless functions, bulkheads and more.
- 24 worked examples. Seventeen teaching scenarios that each isolate one failure mode, and seven reconstructions of real architectures.
- A real discrete-event engine. Finite server slots, gamma-distributed service times and measured percentiles, with no formula standing in for the simulation.
- Faults. Crash a node, restart it, crash one instance, slow it, stall it or make it glitch. Cut a connection, drop packets on it, deliver requests twice or lose the answers coming back. Every fault can be undone, and Reset plays them again at the same moments.
- Can you break it? Say what has to hold, and a search throws faults at the design until it fails, then shrinks the break to the fewest faults that still cause it. Watch it as a replay or send it as a link.
- Correctness checks. Beyond up and fast: was a payment charged twice, was a saved write lost, did a client read its own write? Follow the first request that broke the rule, step by step.
- 18 challenges. Designs that fail as they start, a check that plays three fixed runs of traffic, slot budgets, and a workspace of their own, so your design stays untouched.
- Six real incidents. Published outages rebuilt small, each with its source. Watch one happen, then fix it.
- A learning path. Every example, challenge and outage in 48 steps, with a task card on each example, a first-visit tour, Find the problem and What just happened.
- Traffic shapes. Steady, ramp, spike, daily cycle, bursty and thundering herd, with an uneven key spread for hot shards, and load shown as a multiple of where the design started.
- Live diagram. Requests move along the connections coloured by how they ended, with retries, losses and full waiting lines marked, and each client's own p99 and failure rate.
- Deterministic runs. The same seed and topology replay identically, every time, and a replay link plays the exact run for someone else.
- Explanations built in. Every metric and unit has a plain-language definition one hover away.
- Share links and design files. Send a design as an encrypted link, or save it as a
.breakscalefile that opens on the website and in VS Code. - Made to use quickly. A Ctrl+K command palette, context menus, copy and paste, speed control, a pinned run to compare against, and a presenting mode for teaching a room.
- Private by design. No account, and your designs never leave your machine unless you share them. The website counts page views with Vercel's cookie-free analytics; the extension and the MCP server have no analytics at all.
| Example | What it teaches |
|---|---|
| Single Server | Latency climbs sharply as the database fills up |
| Load Balanced | Three servers share the load, but all still talk to one database |
| Cache Aside | Lower the hit rate and the database takes the whole load |
| Async Workers | The backlog grows when workers fall behind, and drains after |
| Retry Storm | Retries multiply the load that caused them |
| Rate Limited API | Serves slightly less, but what it serves stays fast |
| Circuit Breaker | Break the dependency, watch the circuit trip, then recover |
| Sharded Database | One shard melts while the average still looks healthy |
| Autoscaling Service | Requests fail in the gap while new servers boot |
| Checkout and payments | A retry after a slow answer charges some customers twice |
Plus Netflix, Spotify, Discord, Uber, Twitter/X, Stripe and WhatsApp, reconstructed from published engineering material. Each one says what it models and what it leaves out: they are teaching diagrams, not insider knowledge.
The engine in src/sim is a discrete-event simulator. Requests are real objects moving through
the topology, and a handful of details are what make its results worth trusting.
Finite server slots. A component's capacity is how many requests it can work on at once, and
instances is how many copies of it are running. Anything beyond instances × capacity waits in a
real FIFO queue, and anything beyond the queue limit is shed. A service, worker or lambda holds its
slot while it waits on the parts it calls, so a slow database fills the servers in front of it too.
Service time variance. Service time is a mean plus a coefficient of variation, sampled from a gamma distribution. Variance is what pulls tail latency away from the average, so it is modelled rather than assumed away.
Abandoned work still burns capacity. When a caller times out, the downstream keeps working on a request nobody is waiting for any more. That is why retry storms are something you can watch here rather than something you read about.
Queues acknowledge immediately. A request entering a queue resolves as a success at that point, and the message is buffered for workers, so backlog depth is real and you can watch it build and drain.
Percentiles are measured. p50, p95 and p99 come from a ring buffer of completed request latencies, never from multiplying a mean by a constant.
Runs are deterministic: the same seed and topology replay identically. The test suite checks that
requests are conserved, that the failure breakdown sums to the failure total, that utilisation
stays in bounds, and that no snapshot field is ever NaN or infinite.
You need Bun.
git clone https://github.com/workersio/breakscale.git
cd breakscale
bun install
bun devThen open http://localhost:5173.
src/sim/ the simulation engine. No React, no DOM, no I/O
src/components/ canvas, inspector, metrics, palette
src/content/ glossary text
src/App.tsx shell: layout, the animation loop, persistence
extension/ the VS Code extension
mcp/ the MCP server
worker/ the Cloudflare Worker behind short share links
The engine has no UI dependency, so you can drive it from a script:
import { Engine } from './src/sim/engine';
import { PRESETS } from './src/sim/presets';
const engine = new Engine(PRESETS[0].topology, 42);
for (let i = 0; i < 600; i += 1) engine.advance(1000 / 60);
console.log(engine.snapshot().system);The search behind Can you break it? runs from a script too. verify takes a design and a goal and
returns the smallest set of faults it found that breaks the goal, with a replay of the run:
import { verify } from './src/sim/verify';
import { PRESETS } from './src/sim/presets';
const design = PRESETS.find((p) => p.id === 'checkout')!.topology;
const v = verify(design, { metric: 'doubleCharges', max: 0 }, { chargeable: ['pay'] });
if (v.status === 'broken') console.log(v.schedule, v.measured.actual);The docs cover every goal and option.
- Found a bug, or a number that looks wrong? Open an issue.
- Want to add a component, an example or a better explanation? Start with CONTRIBUTING.md, which covers how the project fits together and the bar a change has to clear.
The short version of that bar is that the numbers have to be true. People learn from this tool, so a plausible-looking number is worse than no number at all.
React, TypeScript and Vite, with Lucide for icons. The canvas is hand-rolled SVG and the charts are drawn directly rather than pulled from a charting library, which keeps the bundle small and the rendering predictable.
The bundled Caveat webfont in public/fonts/Caveat/ is not covered by the MIT licence. It is
licensed separately under the SIL Open Font License 1.1, which ships
alongside the font file as that licence requires. Copyright 2014 The Caveat Project Authors.
