raghukr80/syssim

1. Repository shape

- This is a monorepo with two real runtimes: a TypeScript/React web app in apps/web and an optional Rust simulation engine in packages/sim-engine compiled to WebAssembly.

- The architecture is centered on an in-browser system-design editor plus a simulation runtime; there is no separate backend service in this repo.

2. Primary user-facing application

- apps/web is the main product surface: a single-page app built with React 18, TypeScript, Vite, Tailwind, Zustand, and React Flow.

- It combines diagram editing, configuration panels, live simulation controls, metrics, chaos injection, and report viewing in one client-side application.

3. Core state boundary

- src/stores/diagramStore.ts is the main state hub.

- It likely holds nodes, edges, zones, selected items, simulation state, chaos events, and UI panel state, and acts as the shared data layer between the canvas, palette, properties panes, toolbar, and metrics components.

- For an architecture diagram, this is the central “model” that all UI subsystems read from and write to.

4. Canvas and diagram editor subsystem

- src/components/canvas/ contains the visual composition layer: SimulatorCanvas, ComponentNode, GroupNode, LayoutZones, ParticleCanvas, and AIDesign.

- This layer is responsible for rendering the architecture graph, drag/drop placement, connections, container zones, and traffic-flow visualization.

- React Flow is the key diagramming technology here, so node/edge interactions are modeled as graph objects rather than freeform DOM elements.

5. Palette, toolbar, and workflow controls

- src/components/palette/ComponentPalette.tsx supplies the component catalog for drag-and-drop creation.

- src/components/toolbar/ contains the operational controls: simulation play/stop/speed/traffic, chaos actions, blueprints, cost views, and likely import/export entry points.

- These panels are the command layer that changes the store and drives the canvas and engine.

6. Properties and configuration subsystem

- src/components/properties/PropertiesPanel.tsx, EdgePropertiesPanel.tsx, and IconPicker.tsx handle editing of node/edge metadata.

- This is where component-specific parameters such as RPS, latency, replication, autoscaling, and visual identity are set.

- The boundary is important: editing does not directly simulate anything; it updates the diagram model, which the simulation layer later consumes.

7. Simulation and metrics pipeline

- The simulation experience is split between the engine bindings in src/wasm/ and the visible metrics UI in src/components/metrics/.

- StatusBar, MetricsPanel, EventLog, and ReportModal consume live simulation output such as throughput, latency, errors, utilization, and incident history.

- The data flow is from diagram configuration → simulation engine → event/metric stream → UI panels and downloadable report.

8. Dual simulation runtime

- The repo supports a JavaScript simulation path by default and an optional Rust/WASM backend in packages/sim-engine.

- The WASM boundary is explicit in src/wasm/simulationController.ts plus generated bindings like sim_engine.js and sim_engine_bg.wasm.

- For architecture, this is the main compute boundary: client UI stays in TypeScript while heavy simulation logic can be executed in compiled Rust for fidelity/performance.

9. Simulation engine internals

- The Rust package contains engine.rs, chaos.rs, cost.rs, and components/, indicating separate concerns for core simulation, failure injection, economics, and component behavior.

- This suggests the engine operates on typed component models rather than rendering details, which keeps business simulation logic isolated from the React UI.

- The components module likely maps diagram node types to behavior profiles used by the engine.

10. Chaos engineering subsystem

- Chaos features are first-class, not an overlay: scenarios are categorized, targetable to specific nodes, and track active injections.

- The UI likely coordinates scenario selection and target resolution, while the engine applies effects such as latency, packet loss, resource saturation, and dependency failures.

- This is a distinct event stream feeding the same metrics/reporting pipeline as normal simulation.

11. Assets and icon catalog

- public/icons/ holds a large local SVG library for AWS, Azure, GCP, and general tech icons.

- src/data/icons.ts and src/data/icon-types.ts appear to provide the manifest/catalog used by the palette and icon picker.

- scripts/build-icon-manifest.cjs is a build-time asset indexer, meaning icon discovery is file-system driven rather than fetched from an external service.

12. Blueprints and import/export

- The app supports diagram serialization, deserialization, and blueprint templates, which are managed through the UI and stored as JSON-like project data.

- These flows operate on the same core graph model as the canvas and store, making them persistence/transport boundaries rather than separate business logic layers.

- The downloadable simulation report in Markdown is another export path, but it is generated from simulation results, not from the raw diagram alone.

13. Application entry and deployment surface

- src/main.tsx bootstraps the React app, and index.html is the Vite entrypoint.

- vercel.json indicates the web app is deployable as a static frontend, with no server-side runtime in this repository.

- apps/web/public/ and apps/web/dist/ are the primary asset/output boundaries for deployment.

14. How to draw the architecture

- The cleanest diagram is: user actions enter the React UI shell; the Zustand store is the central coordination layer; the canvas/palette/properties/toolbar/metrics components consume and mutate that store; the simulation controller bridges the store to either JS logic or the optional Rust/WASM engine; metrics, events, and reports flow back to the UI; icons and blueprints are static asset/data inputs.