vijaygupta18/system-design-simulator

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.