How 000sushant/system-design-simulator works
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: simulator.component.ts Simulator · cost.service.ts Cost engine · simulation.service.ts Simulation engine · simulation-canvas.component.ts Canvas
Components 20
Angular frontend
Primary browser application for simulation, validation, and content.
- App shell · Bootstraps the browser application and top-level layout.
frontend/src/main.ts - Shell component · Top-level component that binds the simulator UI into the app shell.
frontend/src/app/app.component.ts - Landing · Marketing and entry screen for the product.
frontend/src/app/features/landing/landing.component.ts - Docs screen · In-app documentation and guidance content.
frontend/src/app/features/documentation/documentation.component.ts - Simulator · Main simulator workspace and user interaction boundary.
frontend/src/app/features/simulator/simulator.component.ts - Challenge panel · Displays challenge metadata, status, and feedback in the simulator.
frontend/src/app/features/simulator/challenge/challenge-panel.component.ts - Onboarding · Guided help and onboarding flow for new users.
frontend/src/app/features/simulator/challenge/onboarding-overlay.component.ts - Canvas · Interactive topology canvas for nodes, ports, and edges.
frontend/src/app/features/canvas animation/simulation-canvas.component.ts - Arch factory · Builds executable architecture models from user-edited topology data.
frontend/src/app/core/services/architecture-factory.service.ts - Graph builder · Converts architecture state into simulation-ready graph structures.
frontend/src/app/core/services/graph-builder.service.ts - Simulation engine · Evaluates traffic, queueing, overload, and failure states over time.
frontend/src/app/core/services/simulation.service.ts - Reviewer · Applies rubric and graph rules to judge challenge solutions.
frontend/src/app/core/services/evaluation/architecture-reviewer.ts - Cost engine · Computes live AWS cost estimates from the modeled architecture.
frontend/src/app/core/services/cost.service.ts - Project storage · Stores user work and architecture drafts locally in the browser.
frontend/src/app/core/services/project-storage.service.ts - Core data · Local data bundles for services, challenges, onboarding, documentation, and region snapshots.
frontend/src/app/core/data/challenges.json - AWS catalog · 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 · Fetches, normalizes, and stores regional AWS pricing data in KV.
worker/src/index.ts - KV store · 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 · 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 · Source of authoritative regional AWS pricing data.
Connections 21
- 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.