xevrion/breakscale

<sub>Title sponsor

Workers IO (YC F26) sponsors Breakscale. Simulation environments for verifying mission-critical software.</sub>

_{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.
• 23 worked examples. Sixteen 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.
• Chaos controls. Crash a node, slow it down, force an error rate, or cut a single link, then watch the failure travel.
• Deterministic runs. The same seed and topology replay identically, every time.
• 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 .breakscale file that opens on the website and in VS Code.
• 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.

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.

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/xevrion/breakscale.git
cd breakscale
bun install
bun dev

Then 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);

• 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.

MIT

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.