breakscale README

The project's README from github.com/xevrion/breakscale. As one markdown file: README.md.

Breakscale: build a system, load it until it breaks, watch why

Try it | Documentation | Contributing

CI Stars Forks MIT licensed PRs welcome

xevrion/breakscale | Trendshift

The Retry Storm example at 100 requests a second: the database is 99.9% busy while goodput is zero

The Retry Storm example at 100 requests a second. The database is at 99.9% busy and goodput is zero, because retries have tripled 100 offered requests into 348 hitting a database that was already full.

Breakscale is a system design simulator for learning how distributed systems behave under load. You place components on a canvas, wire them together, then drag a slider and watch real queueing behaviour emerge: latency percentiles climbing, queues filling, circuit breakers tripping, whole systems collapsing into retry storms.

Every number comes from an actual discrete-event simulation. Nothing is faked, approximated, or animated to look plausible.

Why this exists

Most system design material is static diagrams and rules of thumb. "Add a cache." "Use a queue." It is hard to build intuition for why p99 latency falls off a cliff as utilisation passes 80 percent, or how a short timeout with retries turns one slow database into a total outage.

Breakscale runs the experiment instead. Load the Retry Storm example, drag the traffic up, and watch goodput fall to zero while the database still runs flat out, because every request that completes has already been abandoned by a caller that gave up.

Getting started

You need Bun.

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

Open http://localhost:5173, pick an example from the left, and raise the traffic slider until something goes red.

Features

What is in it

The 23 examples are sixteen teaching scenarios, each isolating one failure mode, plus seven reconstructions of real architectures:

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

Plus Netflix, Spotify, Discord, Uber, Twitter/X, Stripe and WhatsApp, reconstructed from published engineering material. Each names what it models and what it leaves out. They are teaching diagrams, not insider knowledge.

How the simulation works

The engine in src/sim is a discrete-event simulator. Requests are real objects moving through the topology, and a few details are what make the 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. Everything beyond instances × capacity waits in a real FIFO queue, and beyond the queue limit it is shed.

Service time variance. Service time is a mean plus a coefficient of variation, sampled from a gamma distribution. Variance is what makes tail latency diverge 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. This is why retry storms are visible here rather than theoretical.

Queues acknowledge immediately. A request entering a queue resolves as success at that point and the message is buffered for workers. Backlog depth is real, so 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.

The simulation is deterministic: the same seed and topology replay identically. Correctness is covered by a test suite asserting request conservation, that the failure breakdown sums to the failure total, that utilisation stays within bounds, and that no snapshot field is ever NaN or infinite.

Project layout

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

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

Contributing

Contributions are welcome, especially new components, new teaching examples, and better explanations. See CONTRIBUTING.md for how the project is put together and what the bar is for a change.

The short version: the numbers have to be true. This is a tool people learn from, so a plausible looking number is worse than no number at all.

Built with

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.

Star history

Star history for xevrion/breakscale

License

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.

breakscale (xevrion/breakscale)

Searching Database…

1.7K ·GitHub
Breakscale
Что это?Breakscale — симулятор проектирования систем: вы расставляете компоненты на холсте, соединяете их, тянете ползунок трафика и наблюдаете, как настоящая дискретно-событийная симуляция показывает рост задержек, очередей и отказов, — так можно понять, как распределённые системы ведут себя под нагрузкой.
Это просто анимированные схемы или тут реально что-то симулируется?Это настоящий движок дискретно-событийной симуляции, а не визуальный трюк. Запросы моделируются как реальные объекты, движущиеся по топологии с гамма-распределённым временем обслуживания и измеренными перцентилями.
Как это запустить?Запустите локально с Bun и Vite: просто откройте приложение, выберите пример в левой панели и поднимайте ползунок трафика, пока что-нибудь не сломается.
Нужно ли что-то ещё, кроме Bun?Только Bun как JS-рантайм и пакетный менеджер; стек — React, TypeScript и Vite, иконки — Lucide.
Есть ли бэкенд или мои данные куда-то отправляются?Нет, всё работает целиком в браузере — без аккаунтов, бэкенда и телеметрии, так что схемы остаются локально на вашей машине.
Для кого это сделано?Для тех, кто учит или преподаёт распределённые системы и проектирование систем и хочет практической интуиции вместо статичных схем и эмпирических правил.
Нужно ли что-то устанавливать в ОС или это просто работает в браузере?Оно полностью работает в браузере как веб-приложение; из специфичного для ОС — только Bun для локальной разработки.
Он отслеживает использование или отправляет телеметрию?Нет, телеметрии нет, и из вашего браузера ничего не уходит.
Из каких компонентов можно собирать системы?Есть 33 компонента, включая балансировщики нагрузки, кэши, базы данных, очереди, воркеры, CDN, ограничители частоты запросов, circuit breakers, read-реплики, шардированные хранилища, автоскейлеры, брокеры потоков, WebSocket-шлюзы, serverless-функции и переборки (bulkheads).
Какие примеры входят в комплект?23 разобранных примера: 16 обучающих сценариев, каждый из которых изолирует один режим отказа (вроде Retry Storm или Circuit Breaker), плюс 7 реконструкций реальных архитектур из Netflix, Spotify, Discord, Uber, Twitter/X, Stripe и WhatsApp.
Можно ли вносить сбои, чтобы увидеть реакцию системы?Да, хаос-управление позволяет уронить узел, замедлить его, принудительно задать долю ошибок или разорвать конкретную связь, а симуляция детерминирована, так что одинаковые сид и топология всегда воспроизводятся одинаково.
Почему автор построил симулятор, а не просто ещё больше схем?Статичные схемы и эмпирические правила вроде «добавь кэш» не дают настоящей интуиции о том, почему p99-задержка взлетает за 80% загрузки; Breakscale запускает настоящий эксперимент, и вы можете наблюдать это вживую.
What are similar projects?empire, vistep, gitdiagram, bible-strong-avatar-lab, human-atlas, developer-roadmap, loadersz-core, gpt_image_playground
Which topics is it in?teaching-tool, simulator, system-design, canvas, vite, distributed-systems, learning, web-app, react, privacy, education, frontend
Creator
xevrion
Size
1.9 MB
Stars
1.7K
Updated
CommitSep 29
Age
1mo
Commits · 90 Days