The Problem

Designers of distributed systems often rely on static diagrams and rule‑of‑thumb advice. When traffic grows, latency spikes, queues fill, or circuit‑breakers trip, the causal chain is hidden, making it hard to build intuition about load‑induced failure modes.

What This Does

breakscale is a browser‑only simulator that lets users assemble component blocks (load balancer, cache, queue, etc.) on a canvas, wire them, and then drive a traffic slider. Every metric—p99 latency, queue depth, goodput—is produced by a discrete‑event engine in src/sim/engine.ts, not by approximations.

Key UI files: src/App.tsx (root component), src/main.tsx (React bootstrap), and the component library under src/components/. Business‑logic for each vendor model lives in src/content/vendors/*.ts (e.g., aws.ts, gcp.ts). The simulation core (src/sim/*.ts) consumes those models and updates the shared state that drives the visual components.

How It Is Wired

  1. Entry point – index.html loads the Vite bundle. Vite’s dev server (vite dev) serves the compiled JavaScript, which starts at src/main.tsx: ``ts import React from "react"; import { createRoot } from "react-dom/client"; import App from "./App"; createRoot(document.getElementById("root")!).render(<App />); ``
  2. App bootstrap – src/App.tsx sets up global stores (useCoarsePointer, theme, saved designs) and renders the canvas (<Canvas />) alongside side panels (<MainMenu />, <Palette />, etc.).
  3. User interaction – UI controls (traffic slider, chaos toggles) dispatch actions that mutate the simulation state held in src/sim/engine.ts. The engine exposes functions like runStep, enqueueEvent, and processEvent.
  4. Engine loop – src/sim/engine.ts maintains a priority‑queue (src/sim/heap.ts) of timestamped events. Each event handler lives in files such as src/sim/behaviour‑store.ts, behaviour‑messaging.ts, behaviour‑resilience.ts. When the slider changes, engine.setLoad(level) pushes new request‑arrival events; the engine then processes them, invoking vendor‑specific logic from src/content/vendors/* (e.g., aws.queueDelay, azure.circuitBreaker).
  5. Rendering results – After each engine tick, React state updates trigger re‑render of visual components (Canvas.tsx, Metrics.tsx, Trace.tsx). Metrics are formatted by src/theme/*.ts and displayed with plain‑language tooltips (src/components/Tooltip.tsx).
  6. Persistence & sharing – src/share.ts encodes the current topology into a URL fragment; src/savedDesigns.ts reads/writes JSON to localStorage.

All side‑effects stay in‑memory; there is no network or filesystem I/O beyond the client’s storage APIs. The only external dependency is the Vite dev server (or a static host like Vercel). The module graph is shallow: App → component library → simulation engine → vendor modules. No circular imports are present, making the core easy to isolate for testing or replacement.

How To Use It

# Clone the upstream repository
git clone https://github.com/moses-y/breakscale.git
cd breakscale

# Install with Bun (the project’s README specifies Bun)
bun install

# Start the development server
bun dev

Open http://localhost:5173 in a browser. The left panel lists the 23 pre‑built examples (e.g., Retry Storm, Circuit Breaker). Drag the traffic slider to observe latency curves, queue lengths, and failure cascades in real time. No environment variables or external services are required.

Real‑World Use

A teaching team could embed the simulator in a classroom portal. A simple wrapper page might load https://breakscale.vercel.app in an iframe and programmatically set the initial design via the URL fragment (?design=retry‑storm). Instructors can then trigger chaos actions through the UI while students watch the quantitative impact.

Code Health & Issues

  • Low – Missing lockfile for npm – package.json lists dependencies but no package-lock.json or pnpm-lock.yaml. The repo does provide bun.lock, which satisfies Bun but not npm‑based reproducibility.
  • Low – No server‑side tests – All test files target client‑side logic (*.test.tsx, *.test.ts). No integration tests for the Vite build or for the static hosting configuration.
  • Low – CI limited to lint & unit tests – GitHub Actions workflow (.github/workflows/ci.yml) runs bun test but does not perform type‑checking or build verification on a clean environment.

No critical security or licensing concerns are evident; the repository includes a standard MIT LICENSE and a SECURITY.md.

The Bottom Line

breakscale delivers an interactive, accurate simulation of distributed‑system dynamics with a clean React front‑end and well‑isolated engine code. It is ready for educational or demo use, but production‑grade CI (type‑check, lockfile consistency) and broader test coverage would be needed before adopting it as a core teaching platform.