# 000sushant/system-design-simulator architecture

> Architecture diagram of the GitHub repository 000sushant/system-design-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/000sushant/system-design-simulator
- Repository: https://github.com/000sushant/system-design-simulator

## Overview

1. **Overall shape**
   - This is a three-part system: an **Angular frontend** that hosts the simulator, a **Cloudflare Worker** that syncs live AWS pricing, and a small **backend** used as a regional-pricing reader / utility service.
   - Most of the product logic lives in the frontend; the other runtimes exist to feed it pricing data and validation artifacts.

2. **Frontend is the main application boundary**
   - `frontend/src/app` contains the user-facing simulator and nearly all domain logic.
   - The app is split into `core` for reusable logic/state/data and `features` for screens such as the landing page, documentation, and simulator canvas.

3. **Core domain model and data are mostly static and file-driven**
   - `frontend/src/app/core/models` defines architecture and challenge types.
   - `frontend/src/app/core/data` holds the service catalog, onboarding content, challenge definitions, regional pricing snapshots, bottleneck models, and documentation metadata.
   - This makes the simulator largely data-driven rather than hardcoded.

4. **Canvas and architecture editing are the primary interaction loop**
   - `features/simulator` and `features/canvas animation` are the visual workspace for creating topologies and animating traffic.
   - The canvas is backed by `@foblex/flow` according to the README, with the UI centered on nodes, ports, edges, and live simulation state.

5. **Simulation engine is a frontend service pipeline**
   - `core/services/simulation.service.ts`, `graph-builder.service.ts`, and `architecture-factory.service.ts` assemble the user’s topology into an executable graph.
   - The simulation loop evaluates traffic, queueing, overload, and failure states over time, then feeds those results back into the canvas and node status indicators.

6. **Validation and challenge scoring are separate from simulation**
   - `core/services/evaluation/architecture-reviewer.ts` and `graph-rules.ts` implement the rubric system used for challenges.
   - `challenge.service.ts`, `validation-rule.service.ts`, and `vote.service.ts` coordinate challenge metadata, rule checks, scoring, and feedback.
   - This is a distinct boundary from pure runtime simulation: one engine answers “does it work?”, the other answers “does it satisfy the challenge?”

7. **Cost estimation is a first-class subsystem**
   - `core/services/cost.service.ts` computes monthly AWS cost estimates from the modeled architecture.
   - It relies on AWS service metadata, regional pricing tables, and service-specific formulas such as compute, storage, requests, and transfer.
   - Cost is shown as a live panel rather than a post-process report, so it is tightly coupled to topology changes.

8. **Pricing data is synchronized outside the frontend**
   - `worker/` is a Cloudflare Worker that fetches regional AWS pricing from the AWS Pricing API and stores it in Cloudflare KV.
   - `worker/src/fetcher.ts`, `schema-builder.ts`, `stats.ts`, and `regions.ts` suggest a pipeline that retrieves, normalizes, and summarizes pricing data before persistence.
   - The frontend cost service reads those stored rates and falls back to local JSON data such as `frontend/src/app/core/data/regions/us-east-1.json` when needed.

9. **Backend is a lightweight supporting service**
   - `backend/server.js` and `backend/regions.js` indicate a small Node-based API layer, likely used to expose regional pricing or region metadata independently of the frontend.
   - It is not the main product runtime; its role is infrastructure support around the pricing dataset.

10. **Project state and persistence are browser-centric**
   - `project-storage.service.ts` suggests architecture drafts and user work are stored locally in the browser, not in a central app database.
   - `theme.service.ts` and `onboarding.service.ts` are client-side UX concerns, reinforcing that the simulator is primarily a single-page app with local state.

11. **Content and documentation are part of the product**
   - `features/documentation` and the `docs/` folder hold user-facing explanations, challenge authoring guidance, and architecture notes.
   - Challenges are likely authored as structured data plus documentation rather than as bespoke code paths.

12. **Operational tooling is focused on content and pricing integrity**
   - `scripts/validate-pricing.mjs` and `frontend/scripts/validate-challenges.mjs` validate the integrity of pricing and challenge data.
   - The GitHub workflows also include security scanning and challenge validation, which indicates the repo treats datasets and rules as build-time artifacts that must stay consistent.

13. **Useful diagram boundaries**
   - A good architecture diagram should show:
     - **Browser UI / Angular app**
     - **Simulation + validation services inside the frontend**
     - **Local data bundles and browser storage**
     - **Cloudflare Worker + KV as the pricing ingestion path**
     - **AWS Pricing API as the external source**
     - **Optional backend API as a lightweight support layer**
   - The main data flow is: user edits topology → simulation/rules/cost services recompute → UI updates → pricing data is refreshed asynchronously from AWS through the worker.

Main entry points: [`frontend/src/app/features/simulator/simulator.component.ts`](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/simulator/simulator.component.ts) (Simulator), [`frontend/src/app/core/services/cost.service.ts`](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/cost.service.ts) (Cost engine), [`frontend/src/app/core/services/simulation.service.ts`](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/simulation.service.ts) (Simulation engine), [`frontend/src/app/features/canvas animation/simulation-canvas.component.ts`](https://github.com/000sushant/system-design-simulator/blob/HEAD/frontend/src/app/features/canvas%20animation/simulation-canvas.component.ts) (Canvas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Angular frontend"]
  node_app_shell["App shell<br/>Angular root<br/>[main.ts]"]
  node_app_component["Shell component<br/>Angular host<br/>[app.component.ts]"]
  node_landing["Landing<br/>Feature screen"]
  node_documentation["Docs screen<br/>Feature screen"]
  node_simulator_ui["Simulator<br/>Feature screen"]
  node_challenge_panel["Challenge panel<br/>Challenge UI"]
  node_onboarding_overlay["Onboarding<br/>UX overlay"]
  node_canvas["Canvas"]
  node_architecture_factory["Arch factory<br/>Topology assembly"]
  node_graph_builder["Graph builder<br/>Graph pipeline"]
  node_simulation_service["Simulation engine<br/>Runtime simulation"]
  node_evaluation["Reviewer<br/>Challenge evaluation"]
  node_cost_service["Cost engine<br/>Cost estimation<br/>[cost.service.ts]"]
  node_storage[("Project storage<br/>Browser persistence")]
  node_core_data[("Core data<br/>Static datasets<br/>[challenges.json]")]
  node_aws_catalog["AWS catalog<br/>Service metadata"]
end

subgraph group_pricing["Pricing sync"]
  node_worker_pipeline["Pricing worker<br/>Cloudflare Worker<br/>[index.ts]"]
  node_cloudflare_kv[("KV store<br/>Pricing cache")]
end

subgraph group_support["Support backend"]
  node_backend_api["Backend API<br/>Node utility service<br/>[server.js]"]
end

subgraph group_external["External sources"]
  node_aws_pricing_api[("AWS Pricing API<br/>External API")]
end

node_app_shell -->|"hosts"| node_app_component
node_app_component -->|"routes to"| node_simulator_ui
node_simulator_ui -->|"uses"| node_canvas
node_simulator_ui -->|"shows"| node_challenge_panel
node_simulator_ui -->|"guides"| node_onboarding_overlay
node_simulator_ui -->|"links"| node_documentation
node_simulator_ui -->|"enters"| node_landing
node_canvas -->|"emits"| node_architecture_factory
node_architecture_factory -->|"builds"| node_graph_builder
node_graph_builder -->|"feeds"| node_simulation_service
node_simulation_service -->|"updates"| node_canvas
node_simulation_service -->|"triggers"| node_cost_service
node_cost_service -->|"reads"| node_aws_catalog
node_aws_catalog -->|"loads"| node_core_data
node_evaluation -->|"scores"| node_challenge_panel
node_evaluation -->|"uses"| node_core_data
node_storage -->|"persists"| node_simulator_ui
node_worker_pipeline -->|"fetches"| node_aws_pricing_api
node_worker_pipeline -->|"stores"| node_cloudflare_kv
node_cost_service -->|"reads"| node_cloudflare_kv
node_cost_service -->|"fallbacks to"| node_backend_api

click node_app_shell "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/main.ts"
click node_app_component "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/app.component.ts"
click node_landing "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/landing/landing.component.ts"
click node_documentation "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/documentation/documentation.component.ts"
click node_simulator_ui "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/simulator/simulator.component.ts"
click node_challenge_panel "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/simulator/challenge/challenge-panel.component.ts"
click node_onboarding_overlay "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/simulator/challenge/onboarding-overlay.component.ts"
click node_canvas "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/canvas animation/simulation-canvas.component.ts"
click node_architecture_factory "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/architecture-factory.service.ts"
click node_graph_builder "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/graph-builder.service.ts"
click node_simulation_service "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/simulation.service.ts"
click node_evaluation "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/evaluation/architecture-reviewer.ts"
click node_cost_service "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/cost.service.ts"
click node_storage "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/project-storage.service.ts"
click node_core_data "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/data/challenges.json"
click node_aws_catalog "https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/aws-catalog.service.ts"
click node_worker_pipeline "https://github.com/000sushant/system-design-simulator/blob/main/worker/src/index.ts"
click node_backend_api "https://github.com/000sushant/system-design-simulator/blob/main/backend/server.js"

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_shell,node_app_component,node_landing,node_documentation,node_simulator_ui,node_challenge_panel,node_onboarding_overlay,node_canvas,node_architecture_factory,node_graph_builder,node_simulation_service,node_evaluation,node_cost_service,node_storage,node_core_data,node_aws_catalog toneBlue
class node_worker_pipeline,node_cloudflare_kv toneAmber
class node_backend_api toneMint
class node_aws_pricing_api toneRose
```

## Components

### Angular frontend

Primary browser application for simulation, validation, and content.

- [App shell](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/main.ts): Angular root · Bootstraps the browser application and top-level layout. · `frontend/src/main.ts`
- [Shell component](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/app.component.ts): Angular host · Top-level component that binds the simulator UI into the app shell. · `frontend/src/app/app.component.ts`
- [Landing](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/landing/landing.component.ts): Feature screen · Marketing and entry screen for the product. · `frontend/src/app/features/landing/landing.component.ts`
- [Docs screen](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/documentation/documentation.component.ts): Feature screen · In-app documentation and guidance content. · `frontend/src/app/features/documentation/documentation.component.ts`
- [Simulator](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/simulator/simulator.component.ts): Feature screen · Main simulator workspace and user interaction boundary. · `frontend/src/app/features/simulator/simulator.component.ts`
- [Challenge panel](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/simulator/challenge/challenge-panel.component.ts): Challenge UI · Displays challenge metadata, status, and feedback in the simulator. · `frontend/src/app/features/simulator/challenge/challenge-panel.component.ts`
- [Onboarding](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/features/simulator/challenge/onboarding-overlay.component.ts): UX overlay · Guided help and onboarding flow for new users. · `frontend/src/app/features/simulator/challenge/onboarding-overlay.component.ts`
- [Canvas](https://github.com/000sushant/system-design-simulator/blob/HEAD/frontend/src/app/features/canvas%20animation/simulation-canvas.component.ts): Simulation canvas · Interactive topology canvas for nodes, ports, and edges. · `frontend/src/app/features/canvas animation/simulation-canvas.component.ts`
- [Arch factory](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/architecture-factory.service.ts): Topology assembly · Builds executable architecture models from user-edited topology data. · `frontend/src/app/core/services/architecture-factory.service.ts`
- [Graph builder](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/graph-builder.service.ts): Graph pipeline · Converts architecture state into simulation-ready graph structures. · `frontend/src/app/core/services/graph-builder.service.ts`
- [Simulation engine](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/simulation.service.ts): Runtime simulation · Evaluates traffic, queueing, overload, and failure states over time. · `frontend/src/app/core/services/simulation.service.ts`
- [Reviewer](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/evaluation/architecture-reviewer.ts): Challenge evaluation · Applies rubric and graph rules to judge challenge solutions. · `frontend/src/app/core/services/evaluation/architecture-reviewer.ts`
- [Cost engine](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/cost.service.ts): Cost estimation · Computes live AWS cost estimates from the modeled architecture. · `frontend/src/app/core/services/cost.service.ts`
- [Project storage](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/project-storage.service.ts): Browser persistence · Stores user work and architecture drafts locally in the browser. · `frontend/src/app/core/services/project-storage.service.ts`
- [Core data](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/data/challenges.json): Static datasets · Local data bundles for services, challenges, onboarding, documentation, and region snapshots. · `frontend/src/app/core/data/challenges.json`
- [AWS catalog](https://github.com/000sushant/system-design-simulator/blob/main/frontend/src/app/core/services/aws-catalog.service.ts): Service metadata · AWS service definitions and region-aware pricing inputs used by the simulator. · `frontend/src/app/core/services/aws-catalog.service.ts`

### Pricing sync

Cloudflare Worker pipeline that ingests and normalizes regional AWS pricing.

- [Pricing worker](https://github.com/000sushant/system-design-simulator/blob/main/worker/src/index.ts): Cloudflare Worker · Fetches, normalizes, and stores regional AWS pricing data in KV. · `worker/src/index.ts`
- **KV store**: Pricing cache · Persistent store used by the worker to cache normalized regional pricing data.

### Support backend

Lightweight Node service for regional pricing or metadata access.

- [Backend API](https://github.com/000sushant/system-design-simulator/blob/main/backend/server.js): Node utility service · Support service for regional pricing or region metadata access. · `backend/server.js`

### External sources

Outside systems and datasets consumed by the repository.

- **AWS Pricing API**: External API · Source of authoritative regional AWS pricing data.

## Connections

- App shell → Shell component: hosts · The bootstrapped Angular app renders the root shell component.
- Shell component → Simulator: routes to · Main application flow centers on the simulator workspace.
- Simulator → Canvas: uses · The simulator delegates topology editing and animation to the canvas.
- Simulator → Challenge panel: shows · The simulator surfaces challenge state and feedback alongside the canvas.
- Simulator → Onboarding: guides · New-user guidance is layered into the simulator experience.
- Simulator → Docs screen: links · Documentation is part of the product navigation and learning flow.
- Simulator → Landing: enters · Landing screen provides the public entry point into the app.
- Canvas → Arch factory: emits · Canvas edits are transformed into architecture models.
- Arch factory → Graph builder: builds · Topology is converted into graph structures for execution.
- Graph builder → Simulation engine: feeds · Graph output becomes input to the runtime simulation loop.
- Simulation engine → Canvas: updates · Simulation state drives live node and edge status in the canvas.
- Simulation engine → Cost engine: triggers · Topology changes refresh live cost estimates.
- Cost engine → AWS catalog: reads · Cost formulas use AWS service metadata and pricing inputs.
- AWS catalog → Core data: loads · Catalog logic is backed by local static datasets.
- Reviewer → Challenge panel: scores · Challenge review results are displayed in the challenge UI.
- Reviewer → Core data: uses · Rubrics and challenge definitions come from bundled data.
- Project storage → Simulator: persists · Browser storage keeps simulator projects and drafts locally.
- Pricing worker → AWS Pricing API: fetches · Worker pulls authoritative regional pricing from AWS.
- Pricing worker → KV store: stores · Normalized pricing snapshots are written to KV.
- Cost engine → KV store: reads · Frontend cost estimation uses cached regional pricing.
- Cost engine → Backend API: fallbacks to · Backend can provide regional pricing or metadata when needed.