Skip to content

About

System design simulator: sketch a system, send traffic, see what breaks first.

Resources

Contributing

Stars

41 stars

Watchers

1 watching

Forks

Repository files navigation

loadsketch

Sketch a system. Send traffic. See what breaks first.

loadsketch is a system design simulator. Put components on a canvas, connect them, send traffic, and see what each design decision does: where requests queue, how latency grows, and what breaks first.

Try it in your browser → · 繁體中文

A retry storm in loadsketch: after a traffic spike ends, retries keep the API servers overloaded

What it does

  • Discrete-event simulation. Every request goes through every component, with queues, timeouts, retries, circuit breakers and failures. Queueing theory values (M/G/c) are shown next to the simulated results.
  • Find limit. Raises steady traffic step by step until the design stops meeting its SLO (p99 <= 1000 ms, error rate <= 1%), colouring each component on the canvas by busy share and marking what breaks first.
  • "Why it happened". After every run, the simulator tells the story of the run in time order: overload, retries that multiply the load, failures, recovery or a stuck system.
  • 16 kinds of component, and every parameter can be changed. Load balancer, API server, cache, database, queue, CDN and more: instances, concurrency, timeouts, retries, circuit breakers, hit rates.
  • Custom services and presets. A service that is not in the catalog (search, a payment provider, email) is a custom service: you give its name, icon, service time, capacity, error rate, calls and price per instance. Save any component with its settings as a preset; your presets are in the palette, kept in this browser, and can be exported to a file.
  • 47 examples. Retry storm, cache stampede, gray failure, split brain, a bad config push, poison messages in a FIFO queue, a region cutover, and more. Each one has a scenario and says what to look at.
  • On-call practice (8 incidents). A fault is hidden. You see only the users' error rate and p99, pay points to open a component's metrics, name the component and the kind of fault, then fix the design on the canvas.
  • Design briefs (6). Start from requirements and an almost empty canvas: you choose the components and their sizes, then a run shows if the design holds. The brief gives how fast each part is, so a smaller number is not an answer. A reference design is one click away.
  • Constraint problems (3). Meet error-rate and p99 targets inside a monthly budget and a complexity limit. Every run shows its cost at sample prices.
  • Terraform import. Turn Terraform plan JSON into a design (ECS, Lambda, RDS, Aurora, SQS, ElastiCache, CloudFront and more). The import checks capacity first, and each finding runs as a scenario.
  • Versions and compare. Every run keeps a version (the design, the scenario and a summary of the result) in this browser. Pick up to 4 versions to see them side by side: the metrics, and every setting that changed, from what to what. Paired examples open as a comparison with one click, and a share link can carry a comparison.
  • Edit a design with an AI. "Copy a prompt for an AI" copies a format guide and the current design; paste the answer back. The dialog says in plain words what does not fit the format, lists what changed, and replaces the canvas only after you confirm. The guide is also at /llms-full.txt; /llms.txt is a short index of these pages. The site itself does not call any AI model.
  • Designs are JSON files. Designs and scenarios (loadsketch/design@1, loadsketch/scenario@1) have a JSON Schema in schema/. They are easy to read and write for people and AI agents.
  • A CLI. The engine does not use the browser, so the CLI and the UI run the same engine.
  • Share links with no server. The design and the scenario are compressed into the part of the URL after #, which is never sent to a server.
  • English and Traditional Chinese, light and dark.

The examples are simplified models. Some refer to public information about well-known services; they are not the real architecture of any company.

Screenshots

Retry storm

A retry storm in loadsketch: the API servers stay overloaded after the traffic spike ends

"Why it happened"

After a run, the simulator tells the story of the run in time order

47 examples

The list of examples

On-call practice

An on-call incident: only the error rate and p99 are visible

Design briefs

A design brief: requirements, limits and an almost empty canvas

Constraint problems

A constraint problem with a monthly budget and a complexity limit

Terraform import

A design made from Terraform plan JSON, with capacity findings

Find the limit

Click Find limit in the bottom bar to see how much steady traffic a design holds before breaking:

  • How it searches: starts at 1 req/s and doubles until the first failing step (plus one more step past it to check monotonicity), then bisects 4 times between the last passing rate and the first failing rate. Each step runs a warm-up (at least 30 s, longer when autoscaled), measures at peak load (at least 120 s), and stops new traffic to check draining (120 s). It keeps the current scenario's settings (read ratio, client timeout, seed) and strips scenario events (spikes, ramps, faults).
  • What you see on the canvas: as each step completes, cards are coloured by their average busy share while the load ran (excluding the drain period). When the search ends, the canvas highlights the component that saturated or failed first.
  • Pass criteria: front-end p99 <= 1000 ms, front-end error rate <= 1%, background queue fail rate <= 0% (DLQ or expired messages count as failed), and all work drained within 120 s after traffic stops.
  • Scaling and known deviations: high-traffic steps run scaled down (1/k traffic and capacity, targeting ~300,000 requests per run) and multiply counts back, listing any k > 1 steps under assumptions. Because per-instance slots or instances shrink under scaling, queueing waits near saturation are longer than at full size (making limits conservative), and short cache TTLs read a lower hit ratio. See docs/accuracy.md for the measured checks and known deviations.

How accurate is it?

It is a model for learning, not a capacity planning tool.

  • What you can trust: the direction and the mechanism. Which part saturates first, how a slow dependency fills its callers, how retries multiply load, why a system stays down after the spike ends. A comparison of two designs under the same scenario is worth more than one number.
  • What is checked: single stations are tested against queueing theory. For M/M/1 the mean latency is within 5% and the p99 within 10%; M/M/4 and M/D/1 waits are within 10% (tests/queueing.test.ts). The broader accuracy suite (docs/accuracy.md, tests/accuracy.test.ts) covers 25 checks across queueing, bounded rejection, two-stage series, retries, load balancing, scaling and timeouts: 24 pass within tolerance and 1 is documented as a known deviation. Every run is deterministic for a seed, and two designs see the same traffic.
  • What it leaves out: packets and bandwidth, memory and CPU cores, the contents of the data (it counts stale reads and lost writes, but cannot tell you if your data is correct), and the specific behaviour of real products. A "database" here is a generic database, not PostgreSQL.
  • Do not size a production system from an absolute number in a run. Measure the real system.

The assumptions are written down in docs/model.en.md (summary) and docs/model.md (full, Chinese). If a run does not agree with a real system, a formula or a paper, please open an issue. I do not know how far the model is from production systems, and reports are how it gets better.

Run it locally

Requirements: Node.js 22.18 or later.

git clone https://github.com/minchenlee/loadsketch.git
cd loadsketch
npm install
npm run dev        # the simulator: http://127.0.0.1:5317/app/   the intro site: http://127.0.0.1:5317/

CLI

node cli/loadsketch.ts run examples/designs/three-tier.json --scenario examples/scenarios/spike.json --lang en
node cli/loadsketch.ts run examples/designs/three-tier.json --rps 2000 --json     # the result as JSON
node cli/loadsketch.ts validate examples/designs/*.json
node cli/loadsketch.ts fmt examples/designs/three-tier.json --check
node cli/loadsketch.ts import terraform tests/import/fixtures/ecs-rds.plan.json --out design.json

The CLI prints Chinese by default; use --lang en or LOADSKETCH_LANG=en for English.

Using the simulator

  • Drag a component from the left onto the canvas. Drag from the point on the right of a card to the left of another card to connect them.
  • Click a component or a connection to change its parameters on the right.
  • Pick a scenario and a speed at the bottom, then press Run. The dots on a connection are requests: blue is a read, orange is a write, red is a failure. At 1× speed or slower you see single requests.
  • Skip to end computes the whole run at once.
  • To keep a component with its settings, select it and press Save as preset at the top of the right panel. It appears under My presets in the palette.
  • Versions (right panel) lists your runs. To change a design with an AI, use Paste design JSON in the file menu.
  • Panels: ⌘B left, ⌥⌘B right, ⌘J bottom (Ctrl on Windows and Linux).
  • URL options: ?example=three-tier&scenario=spike&speed=0.1&autorun=1&theme=dark&lang=en.

Use it from an AI agent

loadsketch has an Agent Skill for agents such as Claude Code. Download the zip from Paste design JSON in the file menu (Download the skill (zip)), or from the link, and unpack it into ~/.claude/skills/: it adds a loadsketch folder with two files. SKILL.md holds the steps, the rules, the fields and one line per component; reference.md holds the parameters of each component, one section each, and the agent reads only the section it needs. Then ask the agent to change a design: give it the design JSON (Copy only the design JSON), and paste its answer back with Paste design JSON. npm run ai-guide makes these files, /llms.txt and /llms-full.txt from the component catalog.

Tests

npm run test:quick     # about 10 s: fast unit tests and the i18n check
npm run test:slow      # slow unit tests, including the golden test
npm run e2e            # UI tests in headless Chromium
npm run build          # type check, then bundle to dist/

Project layout

Path What it holds
src/schema/ The file formats (zod), the component kinds, the design checks
src/engine/ The discrete-event simulation. No browser APIs
src/learn/ Lessons, on-call incidents, design briefs, constraint problems, cost, diagnosis
src/import/terraform/ Terraform plan JSON → design
src/app/ The simulator UI (React, React Flow). The simulation runs in a Web Worker
src/site/ The intro site. Its live panels are the simulator in an iframe (?embed=1)
cli/ The command line
examples/ Designs and scenarios (JSON)
docs/model.md How the model works and what it assumes (Chinese)
docs/model.en.md The same, as an English summary
docs/design-system.md The look and motion rules of the UI (Chinese)

AGENTS.md has the rules for changing the code, for people and for coding agents.

Design

The UI follows kumo, Cloudflare's open-source design system (MIT). The colour tokens and the look of the cards, buttons, inputs, badges and menus come from kumo; the components are written in this repository and do not use the kumo package. The mapping is at the top of src/app/index.css, and the rules are in docs/design-system.md.

The site runs on Cloudflare Workers static assets (npm run deploy).

Contributing

See CONTRIBUTING.md.

License

MIT

About

System design simulator: sketch a system, send traffic, see what breaks first.

Resources

Contributing

Stars

41 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages