# workersio/breakscale architecture

> Architecture diagram of the GitHub repository workersio/breakscale, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/workersio/breakscale
- Repository: https://github.com/workersio/breakscale

## Overview

Breakscale is a system-design simulator: users assemble architectures, apply traffic and faults, then inspect measured behavior and failure explanations. Its browser UI is the main product surface; the same simulation capabilities are also exposed through a VS Code panel and an MCP server. The graph includes documented learning, challenges, incidents, correctness checks, and sharing. Evidence is limited to the README and the supplied excerpts and source index; unsampled implementation details are not assumed.

Main entry points: [`src/App.tsx`](https://github.com/workersio/breakscale/blob/main/src/App.tsx) (Browser App), [`mcp/src/server.ts`](https://github.com/workersio/breakscale/blob/main/mcp/src/server.ts) (MCP Server), [`src/sim/breakit.ts`](https://github.com/workersio/breakscale/blob/main/src/sim/breakit.ts) (Failure Search), [`src/sim/engine.ts`](https://github.com/workersio/breakscale/blob/main/src/sim/engine.ts) (Discrete-Event Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Design Interface"]
  node_app["Browser App<br/>[App.tsx]"]
  node_canvas["Architecture Canvas<br/>[Canvas.tsx]"]
  node_metrics["Metrics and Trace<br/>[Metrics.tsx]"]
end

subgraph group_simulation["Simulation Engine"]
  node_presets["Design Examples<br/>[presets.ts]"]
  node_engine["Discrete-Event Engine<br/>[engine.ts]"]
  node_behavior["Component Behavior<br/>[behaviour.ts]"]
  node_faults["Fault Injection<br/>[faults.ts]"]
  node_annotations["Diagram Annotations<br/>[annotations.ts]"]
end

subgraph group_learning["Learning and Analysis"]
  node_breaksearch["Failure Search<br/>[breakit.ts]"]
  node_challenge["Challenge Goals<br/>[challenge.ts]"]
  node_judge["Goal Evaluation<br/>[judge.ts]"]
  node_verification["Correctness Checks<br/>[verify.ts]"]
  node_learningpath["Guided Learning<br/>[exampleTask.ts]"]
  node_incidents["Outage Scenarios<br/>[incidents.ts]"]
end

subgraph group_sharing["Design Exchange"]
  node_sharing["Encrypted Sharing<br/>[share.ts]"]
  node_sharestore[("Shared Link Store<br/>[store.ts]")]
end

subgraph group_integrations["Product Integrations"]
  node_extension["VS Code Extension<br/>[extension.ts]"]
  node_webviewstorage[("Panel Persistence<br/>[storage.ts]")]
  node_mcpserver["MCP Server<br/>[server.ts]"]
  node_mcpdesign["Design Builder<br/>[design.ts]"]
  node_mcprun["MCP Simulation<br/>[run.ts]"]
end

node_user(("Engineer"))
node_assistant(("AI Assistant"))

node_user -->|"designs systems"| node_app
node_app -->|"edits topology"| node_canvas
node_app -->|"loads examples"| node_presets
node_app -->|"runs simulation"| node_engine
node_engine -->|"resolves behavior"| node_behavior
node_app -->|"shows results"| node_metrics
node_app -->|"applies faults"| node_faults
node_canvas -->|"stores notes"| node_annotations
node_app -->|"starts search"| node_breaksearch
node_breaksearch -->|"checks goals"| node_challenge
node_breaksearch -->|"simulates trials"| node_engine
node_app -->|"evaluates goals"| node_judge
node_app -.->|"checks correctness"| node_verification
node_app -.->|"guides learning"| node_learningpath
node_app -.->|"loads incidents"| node_incidents
node_app -->|"creates share links"| node_sharing
node_sharing -->|"stores shared designs"| node_sharestore
node_user -->|"opens panel"| node_extension
node_extension -->|"hosts simulator"| node_app
node_extension -.->|"persists designs"| node_webviewstorage
node_assistant -->|"requests design"| node_mcpserver
node_mcpserver -->|"builds topology"| node_mcpdesign
node_mcpserver -->|"runs topology"| node_mcprun
node_mcpserver -->|"searches failures"| node_breaksearch
node_mcpserver -->|"creates share links"| node_sharing
node_mcprun -->|"simulates topology"| node_engine

click node_app "https://github.com/workersio/breakscale/blob/main/src/App.tsx"
click node_canvas "https://github.com/workersio/breakscale/blob/main/src/components/Canvas.tsx"
click node_metrics "https://github.com/workersio/breakscale/blob/main/src/components/Metrics.tsx"
click node_presets "https://github.com/workersio/breakscale/blob/main/src/sim/presets.ts"
click node_engine "https://github.com/workersio/breakscale/blob/main/src/sim/engine.ts"
click node_behavior "https://github.com/workersio/breakscale/blob/main/src/sim/behaviour.ts"
click node_faults "https://github.com/workersio/breakscale/blob/main/src/sim/faults.ts"
click node_annotations "https://github.com/workersio/breakscale/blob/main/src/sim/annotations.ts"
click node_breaksearch "https://github.com/workersio/breakscale/blob/main/src/sim/breakit.ts"
click node_challenge "https://github.com/workersio/breakscale/blob/main/src/sim/challenge.ts"
click node_judge "https://github.com/workersio/breakscale/blob/main/src/sim/judge.ts"
click node_verification "https://github.com/workersio/breakscale/blob/main/src/sim/verify.ts"
click node_learningpath "https://github.com/workersio/breakscale/blob/main/src/learn/exampleTask.ts"
click node_incidents "https://github.com/workersio/breakscale/blob/main/src/sim/incidents.ts"
click node_sharing "https://github.com/workersio/breakscale/blob/main/src/share.ts"
click node_sharestore "https://github.com/workersio/breakscale/blob/main/src/share/store.ts"
click node_extension "https://github.com/workersio/breakscale/blob/main/extension/src/extension.ts"
click node_webviewstorage "https://github.com/workersio/breakscale/blob/main/src/webview/storage.ts"
click node_mcpserver "https://github.com/workersio/breakscale/blob/main/mcp/src/server.ts"
click node_mcpdesign "https://github.com/workersio/breakscale/blob/main/mcp/src/design.ts"
click node_mcprun "https://github.com/workersio/breakscale/blob/main/mcp/src/run.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_canvas,node_metrics toneBlue
class node_presets,node_engine,node_behavior,node_faults,node_annotations toneAmber
class node_breaksearch,node_challenge,node_judge,node_verification,node_learningpath,node_incidents toneMint
class node_sharing,node_sharestore toneRose
class node_extension,node_webviewstorage,node_mcpserver,node_mcpdesign,node_mcprun,node_user,node_assistant toneIndigo
```

## Components

### Design Interface

- [Browser App](https://github.com/workersio/breakscale/blob/main/src/App.tsx): `src/App.tsx`
- [Architecture Canvas](https://github.com/workersio/breakscale/blob/main/src/components/Canvas.tsx): `src/components/Canvas.tsx`
- [Metrics and Trace](https://github.com/workersio/breakscale/blob/main/src/components/Metrics.tsx): `src/components/Metrics.tsx`

### Simulation Engine

- [Design Examples](https://github.com/workersio/breakscale/blob/main/src/sim/presets.ts): `src/sim/presets.ts`
- [Discrete-Event Engine](https://github.com/workersio/breakscale/blob/main/src/sim/engine.ts): `src/sim/engine.ts`
- [Component Behavior](https://github.com/workersio/breakscale/blob/main/src/sim/behaviour.ts): `src/sim/behaviour.ts`
- [Fault Injection](https://github.com/workersio/breakscale/blob/main/src/sim/faults.ts): `src/sim/faults.ts`
- [Diagram Annotations](https://github.com/workersio/breakscale/blob/main/src/sim/annotations.ts): `src/sim/annotations.ts`

### Learning and Analysis

- [Failure Search](https://github.com/workersio/breakscale/blob/main/src/sim/breakit.ts): `src/sim/breakit.ts`
- [Challenge Goals](https://github.com/workersio/breakscale/blob/main/src/sim/challenge.ts): `src/sim/challenge.ts`
- [Goal Evaluation](https://github.com/workersio/breakscale/blob/main/src/sim/judge.ts): `src/sim/judge.ts`
- [Correctness Checks](https://github.com/workersio/breakscale/blob/main/src/sim/verify.ts): `src/sim/verify.ts`
- [Guided Learning](https://github.com/workersio/breakscale/blob/main/src/learn/exampleTask.ts): `src/learn/exampleTask.ts`
- [Outage Scenarios](https://github.com/workersio/breakscale/blob/main/src/sim/incidents.ts): `src/sim/incidents.ts`

### Design Exchange

- [Encrypted Sharing](https://github.com/workersio/breakscale/blob/main/src/share.ts): `src/share.ts`
- [Shared Link Store](https://github.com/workersio/breakscale/blob/main/src/share/store.ts): `src/share/store.ts`

### Product Integrations

- [VS Code Extension](https://github.com/workersio/breakscale/blob/main/extension/src/extension.ts): `extension/src/extension.ts`
- [Panel Persistence](https://github.com/workersio/breakscale/blob/main/src/webview/storage.ts): `src/webview/storage.ts`
- [MCP Server](https://github.com/workersio/breakscale/blob/main/mcp/src/server.ts): `mcp/src/server.ts`
- [Design Builder](https://github.com/workersio/breakscale/blob/main/mcp/src/design.ts): `mcp/src/design.ts`
- [MCP Simulation](https://github.com/workersio/breakscale/blob/main/mcp/src/run.ts): `mcp/src/run.ts`

### Other components

- **Engineer**
- **AI Assistant**

## Connections

- Engineer → Browser App: designs systems
- Browser App → Architecture Canvas: edits topology (evidence: `src/App.tsx`)
- Browser App → Design Examples: loads examples (evidence: `src/App.tsx`)
- Browser App → Discrete-Event Engine: runs simulation (evidence: `src/App.tsx`)
- Discrete-Event Engine → Component Behavior: resolves behavior (evidence: `src/sim/engine.ts`)
- Browser App → Metrics and Trace: shows results (evidence: `src/App.tsx`)
- Browser App → Fault Injection: applies faults
- Architecture Canvas → Diagram Annotations: stores notes (evidence: `src/sim/annotations.ts`)
- Browser App → Failure Search: starts search (evidence: `src/App.tsx`)
- Failure Search → Challenge Goals: checks goals (evidence: `src/sim/breakit.ts`)
- Failure Search → Discrete-Event Engine: simulates trials (evidence: `src/sim/breakit.ts`)
- Browser App → Goal Evaluation: evaluates goals (evidence: `src/App.tsx`)
- Browser App → Correctness Checks: checks correctness
- Browser App → Guided Learning: guides learning
- Browser App → Outage Scenarios: loads incidents (evidence: `src/App.tsx`)
- Browser App → Encrypted Sharing: creates share links
- Encrypted Sharing → Shared Link Store: stores shared designs (evidence: `mcp/src/server.ts`)
- Engineer → VS Code Extension: opens panel
- VS Code Extension → Browser App: hosts simulator
- VS Code Extension → Panel Persistence: persists designs
- AI Assistant → MCP Server: requests design
- MCP Server → Design Builder: builds topology (evidence: `mcp/src/server.ts`)
- MCP Server → MCP Simulation: runs topology (evidence: `mcp/src/server.ts`)
- MCP Server → Failure Search: searches failures (evidence: `mcp/src/server.ts`)
- MCP Server → Encrypted Sharing: creates share links (evidence: `mcp/src/server.ts`)
- MCP Simulation → Discrete-Event Engine: simulates topology (evidence: `mcp/src/run.ts`)
