# vijaygupta18/system-design-simulator architecture

> Architecture diagram of the GitHub repository vijaygupta18/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/vijaygupta18/system-design-simulator
- Repository: https://github.com/vijaygupta18/system-design-simulator

## Overview

1. This repo is a browser-only Next.js 16 app that ships as a static client-side bundle. There is no backend, database, or API layer; all design state, content, simulation, and scoring run locally in React/TypeScript and persist in `localStorage`.

2. The application entry is the App Router under `src/app/`. It provides the global layout and styles, and the main page hosts a single rich workspace rather than multiple server-rendered routes. The repo also includes an Open Graph image generator for sharing.

3. The core UI shell is split into a few persistent regions: a left sidebar, a central ReactFlow-based canvas, a right analysis/control panel, and a top bar/interview bar. `src/components/layout/` and `src/components/sidebar/`, `src/components/panel/`, and `src/components/interview/` define those regions and the interactions between them.

4. The canvas subsystem in `src/components/canvas/` is the main authoring surface. It renders component nodes, text nodes, animated edges, tab bars, and pen overlays/toolbar for annotation. This is where users drag infrastructure blocks, wire them together, and edit connection metadata like protocol and async/sync mode.

5. The application state is centralized in Zustand stores under `src/store/`. Separate stores handle the canvas graph, app-wide UI state, interview flow, simulation state, saved designs, custom problems/components, trade-offs, and pen input. `hydration.ts` and `safeStorage.ts` indicate the client-persistence boundary and prevent storage access issues during initial load.

6. The traffic simulation engine lives in `src/engine/simulator.ts`. It models request flow through the directed graph, including topological propagation, fan-in accumulation, traffic splitting, bottleneck effects, and cycle handling. This engine consumes the current canvas graph and produces per-node metrics used by the UI panel.

7. Scoring is a separate subsystem in `src/scoring/`. `scorer.ts` orchestrates a shared graph-derived evaluation, while rule modules under `src/scoring/rules/` compute the five scoring dimensions: scalability, availability, latency, cost, and trade-offs. The important boundary here is that scoring is connectivity-aware: only wired components on the request path count.

8. Content is data-driven rather than hardcoded into the UI. `src/data/` contains the component catalog, problem catalog, concept library, interview guides, learning path, and trade-off cards. These data files act as the domain model for what can be built, taught, scored, and loaded into the canvas as reference architectures.

9. Customization and interview workflows are first-class. Dialog components under `src/components/dialogs/` cover create/load/save/confirm/support flows, and the interview components provide a timed multi-phase mock interview experience. The interview store and data modules coordinate the phase guidance, timer, and reference prompts.

10. The right panel is where simulation and evaluation become actionable. `src/components/panel/` surfaces capacity calculations, metrics, score reports, simulation controls, trade-off logs, and comparison cards, all fed by store state and simulator/scorer outputs. This creates the feedback loop: build on the canvas, simulate traffic, inspect metrics, then revise.

11. Persistence and portability are emphasized throughout the architecture. Designs can be saved, loaded, exported, and re-opened locally; `src/lib/exportCanvas.ts` handles canvas export, and the README notes PNG/SVG/JSON export support. This makes the app suitable for offline interview prep with no account lifecycle.

12. Supporting utilities and UI primitives stay intentionally thin. `src/components/ui/` contains shared base components, `src/hooks/useBreakpoint.ts` drives responsive behavior, and `src/lib/` holds helper code such as icons, reference loading, and utilities. Styling uses Tailwind CSS v4 with shadcn-style primitives, while ReactFlow, Framer Motion, and perfect-freehand provide the interactive canvas and drawing experience.

Main entry points: [`src/components/layout/app-shell.tsx`](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/layout/app-shell.tsx) (App Shell), [`src/components/canvas/DesignCanvas.tsx`](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/DesignCanvas.tsx) (Design Canvas), [`src/store/hydration.ts`](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/hydration.ts) (Persistence), [`src/components/panel/RightPanel.tsx`](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/panel/RightPanel.tsx) (Right Panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_app_layout["Layout<br/>next app<br/>[layout.tsx]"]
  node_app_page["Workspace Page<br/>next page<br/>[page.tsx]"]
  node_og_image["OG Image<br/>share image"]
end

subgraph group_workspace["Workspace UI"]
  node_top_bar["Top Bar<br/>layout chrome<br/>[top-bar.tsx]"]
  node_sidebar["Sidebar<br/>navigation panel<br/>[Sidebar.tsx]"]
  node_right_panel["Right Panel<br/>analysis panel<br/>[RightPanel.tsx]"]
  node_interview_bar["Interview Bar<br/>workflow bar<br/>[InterviewBar.tsx]"]
  node_app_shell["App Shell<br/>shell coordinator<br/>[app-shell.tsx]"]
end

subgraph group_canvas["Canvas"]
  node_design_canvas["Design Canvas<br/>reactflow canvas<br/>[DesignCanvas.tsx]"]
  node_canvas_tools["Canvas Tools<br/>annotation tools<br/>[PenToolbar.tsx]"]
  node_canvas_edges["Edges<br/>[AnimatedEdge.tsx]"]
  node_canvas_nodes["Nodes<br/>[ComponentNode.tsx]"]
  node_canvas_tabbar["Tab Bar<br/>canvas chrome<br/>[CanvasTabBar.tsx]"]
end

subgraph group_state["State"]
  node_app_store[("App Store<br/>ui state<br/>[appStore.ts]")]
  node_canvas_store[("Canvas Store<br/>graph state<br/>[canvasStore.ts]")]
  node_simulation_store[("Simulation Store<br/>runtime state<br/>[simulationStore.ts]")]
  node_interview_store[("Interview Store<br/>workflow state<br/>[interviewStore.ts]")]
  node_persistence[("Persistence<br/>local storage<br/>[hydration.ts]")]
end

subgraph group_core["Core Logic"]
  node_simulator{{"Simulator<br/>traffic engine<br/>[simulator.ts]"}}
  node_scorer{{"Scorer<br/>evaluation engine<br/>[scorer.ts]"}}
  node_domain_data["Domain Data<br/>catalogs<br/>[components.ts]"]
end

subgraph group_shared["Shared UI"]
  node_export_canvas["Export<br/>[exportCanvas.ts]"]
  node_dialogs["Dialogs<br/>modal flows<br/>[SaveDialog.tsx]"]
  node_ui_primitives["UI Primitives<br/>shared controls<br/>[button.tsx]"]
end

node_app_layout -->|"renders"| node_app_page
node_app_page -->|"uses"| node_app_shell
node_app_shell -->|"contains"| node_top_bar
node_app_shell -->|"contains"| node_sidebar
node_app_shell -->|"contains"| node_design_canvas
node_app_shell -->|"contains"| node_right_panel
node_app_shell -->|"contains"| node_interview_bar
node_design_canvas -->|"renders"| node_canvas_nodes
node_design_canvas -->|"renders"| node_canvas_edges
node_design_canvas -->|"hosts"| node_canvas_tabbar
node_design_canvas -->|"overlays"| node_canvas_tools
node_sidebar -->|"loads"| node_domain_data
node_right_panel -->|"reads"| node_simulation_store
node_right_panel -->|"reads"| node_scorer
node_simulation_store -->|"drives"| node_simulator
node_canvas_store -->|"provides graph"| node_simulator
node_canvas_store -->|"provides graph"| node_scorer
node_scorer -->|"reports"| node_right_panel
node_simulator -->|"reports"| node_right_panel
node_interview_store -->|"drives"| node_interview_bar
node_app_store -->|"controls"| node_app_shell
node_persistence -->|"hydrates"| node_app_store
node_persistence -->|"hydrates"| node_canvas_store
node_persistence -->|"hydrates"| node_simulation_store
node_persistence -->|"hydrates"| node_interview_store
node_dialogs -->|"writes"| node_persistence
node_export_canvas -->|"exports"| node_canvas_store
node_domain_data -->|"feeds"| node_sidebar
node_domain_data -->|"defines criteria"| node_scorer
node_ui_primitives -->|"builds"| node_dialogs
node_ui_primitives -->|"builds"| node_top_bar

click node_app_layout "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/app/layout.tsx"
click node_app_page "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/app/page.tsx"
click node_og_image "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/app/opengraph-image.tsx"
click node_top_bar "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/layout/top-bar.tsx"
click node_sidebar "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/sidebar/Sidebar.tsx"
click node_right_panel "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/panel/RightPanel.tsx"
click node_interview_bar "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/interview/InterviewBar.tsx"
click node_app_shell "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/layout/app-shell.tsx"
click node_design_canvas "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/DesignCanvas.tsx"
click node_canvas_tools "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/PenToolbar.tsx"
click node_canvas_edges "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/edges/AnimatedEdge.tsx"
click node_canvas_nodes "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/nodes/ComponentNode.tsx"
click node_canvas_tabbar "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/CanvasTabBar.tsx"
click node_app_store "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/appStore.ts"
click node_canvas_store "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/canvasStore.ts"
click node_simulation_store "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/simulationStore.ts"
click node_interview_store "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/interviewStore.ts"
click node_persistence "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/hydration.ts"
click node_simulator "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/engine/simulator.ts"
click node_scorer "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/scoring/scorer.ts"
click node_domain_data "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/data/components.ts"
click node_export_canvas "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/lib/exportCanvas.ts"
click node_dialogs "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/dialogs/SaveDialog.tsx"
click node_ui_primitives "https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/ui/button.tsx"

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_layout,node_app_page,node_og_image toneBlue
class node_top_bar,node_sidebar,node_right_panel,node_interview_bar,node_app_shell toneAmber
class node_design_canvas,node_canvas_tools,node_canvas_edges,node_canvas_nodes,node_canvas_tabbar toneMint
class node_app_store,node_canvas_store,node_simulation_store,node_interview_store,node_persistence toneRose
class node_simulator,node_scorer,node_domain_data toneIndigo
class node_export_canvas,node_dialogs,node_ui_primitives toneTeal
```

## Components

### App Shell

Next.js app router, global layout, and top-level page surface.

- [Layout](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/app/layout.tsx): next app · Global app shell and styling entry. · `src/app/layout.tsx`
- [Workspace Page](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/app/page.tsx): next page · Main single-screen client workspace. · `src/app/page.tsx`
- [OG Image](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/app/opengraph-image.tsx): share image · Open Graph image generator for sharing. · `src/app/opengraph-image.tsx`

### Workspace UI

Persistent authoring, navigation, and feedback regions.

- [Top Bar](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/layout/top-bar.tsx): layout chrome · Header controls and session navigation. · `src/components/layout/top-bar.tsx`
- [Sidebar](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/sidebar/Sidebar.tsx): navigation panel · Left rail for problems, components, and learning. · `src/components/sidebar/Sidebar.tsx`
- [Right Panel](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/panel/RightPanel.tsx): analysis panel · Simulation, metrics, and scoring feedback. · `src/components/panel/RightPanel.tsx`
- [Interview Bar](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/interview/InterviewBar.tsx): workflow bar · Timed interview phase control. · `src/components/interview/InterviewBar.tsx`
- [App Shell](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/layout/app-shell.tsx): shell coordinator · Composes persistent regions into one workspace. · `src/components/layout/app-shell.tsx`

### Canvas

ReactFlow-based design surface and annotation tools.

- [Design Canvas](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/DesignCanvas.tsx): reactflow canvas · Main graph editor and canvas host. · `src/components/canvas/DesignCanvas.tsx`
- [Canvas Tools](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/PenToolbar.tsx): annotation tools · Pen overlay and toolbar for markup. · `src/components/canvas/PenToolbar.tsx`
- [Edges](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/edges/AnimatedEdge.tsx): graph edges · Animated connection rendering and edge types. · `src/components/canvas/edges/AnimatedEdge.tsx`
- [Nodes](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/nodes/ComponentNode.tsx): graph nodes · Component and text node renderers. · `src/components/canvas/nodes/ComponentNode.tsx`
- [Tab Bar](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/canvas/CanvasTabBar.tsx): canvas chrome · Canvas tab navigation and mode switching. · `src/components/canvas/CanvasTabBar.tsx`

### State

Zustand stores and persistence boundary.

- [App Store](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/appStore.ts): ui state · Global UI and layout state. · `src/store/appStore.ts`
- [Canvas Store](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/canvasStore.ts): graph state · Authoring graph, nodes, edges, and metadata. · `src/store/canvasStore.ts`
- [Simulation Store](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/simulationStore.ts): runtime state · Traffic model inputs and results. · `src/store/simulationStore.ts`
- [Interview Store](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/interviewStore.ts): workflow state · Interview phases, timer, and prompts. · `src/store/interviewStore.ts`
- [Persistence](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/store/hydration.ts): local storage · Hydration-safe client storage boundary. · `src/store/hydration.ts`

### Core Logic

Simulation, scoring, and domain data.

- [Simulator](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/engine/simulator.ts): traffic engine · Propagates requests through the directed graph. · `src/engine/simulator.ts`
- [Scorer](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/scoring/scorer.ts): evaluation engine · Coordinates graph-derived scoring. · `src/scoring/scorer.ts`
- [Domain Data](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/data/components.ts): catalogs · Components, problems, concepts, interview guides, and cards. · `src/data/components.ts`

### Shared UI

Reusable primitives and dialogs.

- [Export](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/lib/exportCanvas.ts): export utility · Canvas export and portability helpers. · `src/lib/exportCanvas.ts`
- [Dialogs](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/dialogs/SaveDialog.tsx): modal flows · Create, load, save, confirm, and support dialogs. · `src/components/dialogs/SaveDialog.tsx`
- [UI Primitives](https://github.com/vijaygupta18/system-design-simulator/blob/main/src/components/ui/button.tsx): shared controls · Reusable buttons, tabs, sliders, tooltips, and toast. · `src/components/ui/button.tsx`

## Connections

- Layout → Workspace Page: renders · Root layout mounts the main page.
- Workspace Page → App Shell: uses · Page delegates composition to the shell.
- App Shell → Top Bar: contains · Shell includes the top bar.
- App Shell → Sidebar: contains · Shell includes the left sidebar.
- App Shell → Design Canvas: contains · Shell anchors the central workspace.
- App Shell → Right Panel: contains · Shell includes the analysis panel.
- App Shell → Interview Bar: contains · Shell includes interview workflow controls.
- Design Canvas → Nodes: renders · Canvas uses node renderers for graph entities.
- Design Canvas → Edges: renders · Canvas uses custom edge rendering.
- Design Canvas → Tab Bar: hosts · Canvas exposes tabbed modes and views.
- Design Canvas → Canvas Tools: overlays · Annotation tools sit on top of the canvas.
- Sidebar → Domain Data: loads · Sidebar presents problems, components, and learning content.
- Right Panel → Simulation Store: reads · Panel displays simulation outputs.
- Right Panel → Scorer: reads · Panel shows scoring results and trade-offs.
- Simulation Store → Simulator: drives · Simulation state feeds the engine.
- Canvas Store → Simulator: provides graph · Current canvas graph is the simulation input.
- Canvas Store → Scorer: provides graph · Scoring evaluates the current wired design.
- Scorer → Right Panel: reports · Score summaries surface in the UI.
- Simulator → Right Panel: reports · Per-node metrics surface in the UI.
- Interview Store → Interview Bar: drives · Interview state controls the bar.
- App Store → App Shell: controls · Global UI state affects shell behavior.
- Persistence → App Store: hydrates · Client-safe storage initializes UI state.
- Persistence → Canvas Store: hydrates · Saved designs restore the graph.
- Persistence → Simulation Store: hydrates · Simulation settings and results persist locally.
- Persistence → Interview Store: hydrates · Interview progress persists locally.
- Dialogs → Persistence: writes · Save/load/create flows update local storage.
- Export → Canvas Store: exports · Canvas state can be exported as portable artifacts.
- Domain Data → Sidebar: feeds · Catalogs populate selection and learning UI.
- Domain Data → Scorer: defines criteria · Scoring references catalog-driven problem context.
- UI Primitives → Dialogs: builds · Dialogs are assembled from shared controls.
- UI Primitives → Top Bar: builds · Header controls reuse primitives.