Breakscale: a free system design simulator that shows where your architecture breaks
Breakscale is an open source system design simulator: you place load balancers, caches, databases and queues on a canvas, wire them together, raise the traffic and watch in real time where and why your architecture breaks. The p50, p95 and p99 latencies, the queues and the errors are not drawings: they come from a discrete-event simulation in which every request is an object travelling through the system.
It is free, MIT licensed and comes in three forms: in the browser, as a VS Code extension and as an MCP server, so Claude Code, Codex or Cursor can turn your repository's architecture into a design and tell you what fails first. We cloned workersio/breakscale (commit 283ddfe from November 11, 2026; extension and MCP server at version 0.1.1), ran it locally and used its own engine to measure the most instructive example: the retry storm.
What Breakscale is
- Repository: github.com/workersio/breakscale, about 2,200 stars as of mid-November 2026.
- License: MIT for the app, the VS Code extension (
extension/LICENSE) and the MCP server (mcp/LICENSE). The one exception is the bundled Caveat handwriting font inpublic/fonts/Caveat/, which ships under its own SIL Open Font License 1.1. You can use, modify and deploy it in commercial projects as long as you keep the copyright notice. - Stack: React 19, TypeScript and Vite; the canvas is hand-rolled SVG and the charts are drawn without a charting library. The engine lives in
src/simand has no React or DOM dependency. - Content: 33 components and 23 examples: 16 scenarios that each isolate one failure mode and 7 reconstructions of public architectures (Netflix, Spotify, Discord, Uber, Twitter/X, Stripe and WhatsApp), which the project itself describes as teaching diagrams, not insider knowledge.
- Privacy: no account. Designs stay in your browser unless you share them, and a shared link is encrypted before it leaves, with the key in the URL's
#fragment that browsers never send to a server. The website counts page views with Vercel's cookie-free analytics; the extension and the MCP server have no analytics.
If you want the theory, the visual guide System Design 101 explains the concepts in diagrams. Breakscale is the other half: instead of reading that "a cache helps", you lower the hit rate and watch the database melt.
What it simulates and why its numbers are credible
Many diagram tools paint an arrow red when something "looks" saturated. Breakscale runs the simulation. According to the README and the code in src/sim, the engine rests on five rules:
| Rule | What it means in practice |
|---|---|
| Finite server slots | Each component works on `capacity` requests at once for each of its `instances`. Anything beyond that waits in a real FIFO queue, and anything that does not fit in the queue is shed. |
| Variable service time | A mean plus a coefficient of variation, sampled from a gamma distribution. That variance is what pulls p99 away from the average. |
| Abandoned work still burns capacity | When a caller gives up, the downstream keeps working on a request nobody wants any more. That is where retry storms come from. |
| Queues acknowledge immediately | A request entering a queue counts as a success and the message is buffered for workers, so backlog is real and you can watch it build and drain. |
| Measured percentiles | p50, p95 and p99 come from a ring buffer of real latencies, never from multiplying the mean by a constant. |
Runs are deterministic: the same seed and topology replay exactly. The tests check that no requests are lost, that the failure breakdown adds up to the total and that no value is NaN or infinite. There are also chaos controls (crash a node, slow it down, force an error rate or cut a link) and a plain-language definition of every metric on hover.
How to use it in the browser or in VS Code
The quickest way is the official site, breakscale.tech: pick an example and drag the Offered load control (requests per second, on a log scale from 1 to 5,000) until something turns red. No sign-up needed.
If you would rather stay in your editor, install Breakscale from the VS Code Marketplace and run Open Breakscale from the command palette. It opens the same simulator in a panel next to your code, with the same engine and examples, and works offline. Designs are saved in VS Code's storage and move between the website and the editor through a share link or a .breakscale file.
Running it on your machine
You need Bun. This is how we started it:
git clone --depth 1 https://github.com/workersio/breakscale.git
cd breakscale
bun install
bun devOpen http://localhost:5173. bun install installed 110 packages in about 3 seconds. On start-up Vite printed a dependency-scan error because it cannot find @modelcontextprotocol/ext-apps, which the widget in mcp/widget/ imports and which the root install does not include. It does not affect the simulator: the app loaded and worked normally. To silence it, also run bun install inside mcp/.
The engine has no UI dependency, so you can drive it from a script. This is the one we used to measure the example in the next section (Bun runs TypeScript directly):
import { Engine } from './src/sim/engine';
import { PRESETS } from './src/sim/presets';
const preset = PRESETS.find((p) => p.id === 'retry-storm')!;
for (const rps of [40, 60, 80, 85, 90, 100]) {
const topology = structuredClone(preset.topology);
topology.nodes.find((n) => n.id === 'client')!.config.rps = rps;
const engine = new Engine(topology, 42); // fixed seed: reproducible result
for (let i = 0; i < 60 * 120; i += 1) engine.advance(1000 / 60); // 120 simulated seconds
const s = engine.snapshot().system;
console.log(rps, s.goodputRps.toFixed(1), ((s.totalFailed / s.totalRequests) * 100).toFixed(1));
}bun sweep.tsReal test: the retry storm
The Retry storm example has three parts: a client, an API with a 250 ms timeout and 2 retries, and a small database: 4 requests at a time, 40 ms each on average, which is a theoretical ceiling of 100 requests per second. At 45 requests per second everything is fine: the database is 58% busy and system p99 is around 100 ms.
With the script above we swept the load for 120 simulated seconds with seed 42:
| Offered load | Goodput (useful requests/s) | Failed requests | Database utilisation |
|---|---|---|---|
| 40/s | 36.7 | 0% | 35% |
| 60/s | 53.3 | 0% | 55% |
| 80/s | 68.9 | 0% | 68% |
| 85/s | **0** | **93.1%** | 99.9% |
| 90/s | 0 | 79.7% | 99.9% |
| 100/s | 0 | 97.7% | 99.9% |
The jump from 80 to 85 requests per second is the key point. The database has not reached its ceiling of 100 yet, but queueing starts to exceed 250 ms, the API times out and retries twice, so each request becomes up to three. The screenshot at the top shows the result: the client sends 97 requests per second and the API pushes 283 per second at a database that was already full. The database runs at 99.9% and goodput is zero, because everything it finishes has already been abandoned by whoever asked for it. That is the "abandoned work still burns capacity" rule in action.
How to fix it without adding servers
We tried two changes to the API at 85 requests per second:
| Change | Goodput | Failures | p99 |
|---|---|---|---|
| Original (250 ms timeout, 2 retries) | 0 | 93.1% | — |
| No retries (250 ms timeout) | 81.1/s | 1.5% | 156 ms |
| 1 s timeout (2 retries) | 81.1/s | 0% | 156 ms |
With a 1 s timeout the system holds even at 100 requests per second, right at the database's physical limit: 0% errors in the UI and a p99 that rises to about 900 ms, because requests now wait instead of multiplying. In our 120 s sweep at that load the failure rate was 7.4%, the price of running right at the ceiling. The lesson is one people often read without really getting: a short timeout with retries amplifies the overload that triggered it.
To change it in the UI, click API Server, and in the inspector on the right, under When things go wrong, move Timeout or change Retries. The What just happened panel logs each change and each consequence with its exact second.
Breakscale with Claude Code and other agents (MCP)
Breakscale is also an MCP server with five tools:
| Tool | What it does |
|---|---|
| `read_me` | Explains the design format, every component and how to map real code onto components |
| `create_view` | Validates a design, simulates 30 s of it and shows it on the canvas |
| `export_design` | Returns the design as a `.breakscale` file |
| `open_design` | Reads a breakscale.tech share link so you can ask for changes to it |
| `break_it` | Throws faults at the design until it misses a goal you set, and links to a replay |
For Claude Code, with the hosted server (nothing to install):
claude mcp add --transport http --scope user breakscale https://mcp.breakscale.tech/mcpOr on your machine, with Node 20 or newer, so the simulation runs locally:
claude mcp add --scope user breakscale -- npx -y breakscale-mcp --stdio--scope user makes it available in all your projects. Check it with /mcp inside Claude Code. In claude.ai you add it under Customize › Connectors › Add custom connector with the URL https://mcp.breakscale.tech/mcp and no OAuth. Note that Claude Code, Codex and Gemini CLI only get numbers and a link: the interactive canvas inside the chat appears in clients that support MCP Apps, such as claude.ai, Claude Desktop, VS Code with Copilot or Cursor. If you want to build a server like this, we have a guide to mcp-builder.
Useful prompts once it is connected (suggested by the authors):
- "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?"
The first one is the most valuable for a small team: the agent reads your code, infers the components and tells you where the bottleneck is before a real traffic spike finds it. Always ask it which numbers it guessed, because your database capacity or your API's service time cannot be read from the code.
How much it costs
| Option | Cost | When to choose it |
|---|---|---|
| breakscale.tech website | USD 0, no account | Learning, trying ideas and sharing designs |
| VS Code extension | USD 0, works offline | Working next to your code without relying on the website |
| Hosted MCP server | USD 0 for Breakscale; you only pay your assistant's tokens (or your Claude subscription) | Letting the agent model your architecture with nothing to install |
| Local MCP server (`npx`) | USD 0; the simulation uses your CPU | When you do not want your designs to leave your machine |
| Deploying your own copy | Whatever static hosting you already use; short links use an optional Cloudflare Worker (`worker/`) | Internal training or a version adapted for your team |
Compared with paid system design courses or subscription diagramming tools, the cheapest option for almost any case is the website or the extension: zero dollars and the same engine. The MCP server is the only option with an indirect cost: the tokens your assistant spends reading the repository and generating the design.
Common errors
- "Failed to resolve @modelcontextprotocol/ext-apps" when running
bun dev. That is the dependency scan of themcp/widget. The simulator works anyway; if it bothers you, runbun installinsidemcp/. - The system "holds" at 85 requests per second in one run and collapses in another. The onset of the collapse is stochastic: it depends on when the first slow batch arrives. Use the same seed to compare changes; the project's own test (
retryStorm.test.ts) documents failure rates between 40% and 95% depending on the seed right at the knee. - I don't see the canvas in Claude Code. That is expected: Claude Code gets metrics and a breakscale.tech link. Open it in the browser or use a client with MCP Apps.
- My architecture's numbers don't match production. The simulator is only as good as the parameters you give it. Measure the real service time and concurrency of your database and API first, and feed them into the design.
Frequently asked questions
Is Breakscale free for commercial use? Yes. The code is MIT, so you can use it at your company, modify it and deploy it. Keep the copyright notice, and remember that the bundled Caveat font is under OFL 1.1.
Do I need to know system design to use it? No. The examples are built for learning: each one has a note on the canvas telling you what to change and what should happen, and every metric has its definition on hover.
Are my designs uploaded to a server? Not unless you share them, and then they are encrypted in your browser before being sent. With the hosted MCP server your assistant does send the design to mcp.breakscale.tech to simulate it; if you don't want that, use npx -y breakscale-mcp --stdio.
Is it useful for system design interview prep? For understanding the why behind the answers, yes: watching p99 shoot up once utilisation passes 80%, or a retry take down a system, sticks better than a memorised rule.
Conclusion
Breakscale turns system design rules ("add a cache", "be careful with retries") into experiments you can repeat and measure. Start with the Retry storm example on breakscale.tech, raise the load from 80 to 85 and then change the API timeout. Once it clicks, connect the MCP server to Claude Code and ask it to model your own project's architecture: it is the cheapest way to find the bottleneck before your users do.
// source code
Help us grow
codigoagente is free, with no paywalls. If this article helped you, any of these keeps the blog going.
- Share it with someone who'll find it usefulWhatsAppLinkedInXFacebook
- Meet our sponsorSafe Build Labs
More on Open source tools

- Free alternatives to paid apps
- Design, image and video

- Free alternatives to paid apps
- Run it on your server

- Claude Code
- Free alternatives to paid apps