xevrion/breakscale

Build a system, load it until it breaks, and watch why. A system design simulator for learning distributed systems

Summary

Breakscale is an open-source simulator that lets engineers assemble distributed systems from 33 components (load balancers, caches, databases, queues, workers, and more) and watch what happens as traffic rises. Rather than static diagrams, it runs a real discrete-event simulation: requests are objects moving through the topology, and latency percentiles, queue depth, and utilisation come from measured behaviour. It is MIT-licensed and ships as a web app, a VS Code extension, and an MCP server for AI assistants.

What it is useful for

The tool targets engineers who want to understand why systems fail under load, not just that they do. The README highlights the Retry Storm example: at 100 req/s the database sits at 99.9% busy while goodput drops to zero, because abandoned requests keep working after callers time out. Other built-in scenarios isolate single failure modes — cache miss rates pushing load to the database, sharded databases where one shard melts while averages look healthy, autoscaling gaps that drop requests before new servers boot, and rate limiters that "serve slightly less, but what they serve stays fast."

Seven additional reconstructions (Netflix, Spotify, Discord, Uber, Twitter/X, Stripe, WhatsApp) are explicitly described as "teaching diagrams, not insider knowledge" — each states what it models and what it leaves out.

Chaos controls let you crash a node, slow it down, force an error rate, or cut a single link, so failures can be traced as they travel. Runs are deterministic given a seed and topology, and the engine in src/sim has no UI dependency, so the same code can be driven from a script for repeatable tests.

How engineers can use it

Three documented entry points:

• Browser: open https://breakscale.tech, pick an example, drag the traffic slider. No account is required; shared designs are encrypted client-side.
• VS Code: install from the Marketplace and run "Open Breakscale" from the command palette. The extension works offline and uses VS Code's local storage; designs move between editor and website via share links or .breakscale files.
• AI assistants: connect the hosted MCP server at https://mcp.breakscale.tech/mcp to Claude, Copilot, Cursor, Codex, and others:

claude mcp add --transport http --scope user breakscale https://mcp.breakscale.tech/mcp

Or run it locally with npx -y breakscale-mcp --stdio (requires Node 20).

For local development, the README requires Bun:

git clone https://github.com/xevrion/breakscale.git
cd breakscale
bun install
bun dev

Then open http://localhost:5173.

Documented caveats: Local development requires Bun. The bundled Caveat webfont under public/fonts/Caveat/ is licensed separately under SIL OFL 1.1, not MIT. Real-architecture reconstructions are teaching diagrams with stated omissions rather than faithful models. Full setup details are in the README and at https://docs.breakscale.tech.