# raghukr80/syssim architecture

> Architecture diagram of the GitHub repository raghukr80/syssim, 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/raghukr80/syssim
- Repository: https://github.com/raghukr80/syssim

## Overview

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.

Main entry points: [`apps/web/src/stores/diagramStore.ts`](https://github.com/raghukr80/syssim/blob/main/apps/web/src/stores/diagramStore.ts) (Diagram store), [`apps/web/src/components/canvas/SimulatorCanvas.tsx`](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/canvas/SimulatorCanvas.tsx) (Canvas editor), [`apps/web/src/main.tsx`](https://github.com/raghukr80/syssim/blob/main/apps/web/src/main.tsx) (App shell), [`apps/web/src/components/toolbar/Toolbar.tsx`](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/toolbar/Toolbar.tsx) (Command bar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_web["Web app"]
  node_node_entry["App shell<br/>Vite/React entry<br/>[main.tsx]"]
  node_node_store[("Diagram store<br/>Zustand state<br/>[diagramStore.ts]")]
  node_node_canvas["Canvas editor<br/>React Flow canvas"]
  node_node_nodes["Node views<br/>Canvas primitives<br/>[ComponentNode.tsx]"]
  node_node_zones["Layout zones<br/>Canvas overlay<br/>[LayoutZones.tsx]"]
  node_node_particles(("Traffic viz<br/>Canvas effect<br/>[ParticleCanvas.tsx]"))
  node_node_palette["Component palette<br/>Catalog UI"]
  node_node_toolbar["Command bar<br/>Workflow controls<br/>[Toolbar.tsx]"]
  node_node_controls["Simulation controls<br/>Run controls"]
  node_node_chaos["Chaos panel<br/>Scenario UI<br/>[ChaosPanel.tsx]"]
  node_node_blueprints["Blueprint panel<br/>Template UI<br/>[BlueprintPanel.tsx]"]
  node_node_properties["Properties pane<br/>Inspector UI"]
  node_node_edgeprops["Edge editor<br/>Inspector UI"]
  node_node_metrics["Metrics panel<br/>Observability UI<br/>[MetricsPanel.tsx]"]
  node_node_status["Status bar<br/>Live summary<br/>[StatusBar.tsx]"]
  node_node_report["Report modal<br/>Export UI<br/>[ReportModal.tsx]"]
  node_node_controller["Sim controller<br/>WASM bridge"]
  node_node_wasm["WASM module<br/>Generated bindings<br/>[sim_engine.js]"]
end

subgraph group_group_engine["Simulation engine"]
  node_node_engine["Rust engine<br/>Simulation core<br/>[engine.rs]"]
  node_node_chaoscore["Chaos logic<br/>Engine module<br/>[chaos.rs]"]
  node_node_cost["Cost model<br/>Engine module<br/>[cost.rs]"]
  node_node_components["Component models<br/>Engine module<br/>[mod.rs]"]
end

subgraph group_group_assets["Assets and data"]
  node_node_icondata["Icon catalog<br/>Asset manifest<br/>[icons.ts]"]
  node_node_icons["SVG library<br/>Static assets"]
end

node_node_entry -->|"initializes"| node_node_store
node_node_entry -->|"renders"| node_node_canvas
node_node_entry -->|"mounts"| node_node_toolbar
node_node_entry -->|"mounts"| node_node_metrics
node_node_store -->|"feeds"| node_node_canvas
node_node_store -->|"feeds"| node_node_palette
node_node_store -->|"feeds"| node_node_properties
node_node_store -->|"feeds"| node_node_edgeprops
node_node_store -->|"drives"| node_node_controls
node_node_store -->|"drives"| node_node_chaos
node_node_store -->|"serializes"| node_node_blueprints
node_node_canvas -->|"composes"| node_node_nodes
node_node_canvas -->|"layers"| node_node_zones
node_node_canvas -->|"layers"| node_node_particles
node_node_palette -->|"uses"| node_node_icondata
node_node_icondata -->|"indexes"| node_node_icons
node_node_toolbar -->|"contains"| node_node_controls
node_node_toolbar -->|"contains"| node_node_chaos
node_node_toolbar -->|"contains"| node_node_blueprints
node_node_properties -->|"updates"| node_node_store
node_node_edgeprops -->|"updates"| node_node_store
node_node_controller -->|"reads"| node_node_store
node_node_controller -->|"calls"| node_node_wasm
node_node_wasm -->|"bridges"| node_node_engine
node_node_engine -->|"includes"| node_node_chaoscore
node_node_engine -->|"includes"| node_node_cost
node_node_engine -->|"includes"| node_node_components
node_node_wasm -->|"feeds"| node_node_metrics
node_node_wasm -->|"feeds"| node_node_report

click node_node_entry "https://github.com/raghukr80/syssim/blob/main/apps/web/src/main.tsx"
click node_node_store "https://github.com/raghukr80/syssim/blob/main/apps/web/src/stores/diagramStore.ts"
click node_node_canvas "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/canvas/SimulatorCanvas.tsx"
click node_node_nodes "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/canvas/ComponentNode.tsx"
click node_node_zones "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/canvas/LayoutZones.tsx"
click node_node_particles "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/canvas/ParticleCanvas.tsx"
click node_node_palette "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/palette/ComponentPalette.tsx"
click node_node_toolbar "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/toolbar/Toolbar.tsx"
click node_node_controls "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/toolbar/SimulationControls.tsx"
click node_node_chaos "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/toolbar/ChaosPanel.tsx"
click node_node_blueprints "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/toolbar/BlueprintPanel.tsx"
click node_node_properties "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/properties/PropertiesPanel.tsx"
click node_node_edgeprops "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/properties/EdgePropertiesPanel.tsx"
click node_node_metrics "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/metrics/MetricsPanel.tsx"
click node_node_status "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/metrics/StatusBar.tsx"
click node_node_report "https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/metrics/ReportModal.tsx"
click node_node_controller "https://github.com/raghukr80/syssim/blob/main/apps/web/src/wasm/simulationController.ts"
click node_node_icondata "https://github.com/raghukr80/syssim/blob/main/apps/web/src/data/icons.ts"
click node_node_icons "https://github.com/raghukr80/syssim/tree/main/apps/web/public/icons"
click node_node_wasm "https://github.com/raghukr80/syssim/blob/main/apps/web/src/wasm/sim_engine.js"
click node_node_engine "https://github.com/raghukr80/syssim/blob/main/packages/sim-engine/src/engine.rs"
click node_node_chaoscore "https://github.com/raghukr80/syssim/blob/main/packages/sim-engine/src/chaos.rs"
click node_node_cost "https://github.com/raghukr80/syssim/blob/main/packages/sim-engine/src/cost.rs"
click node_node_components "https://github.com/raghukr80/syssim/blob/main/packages/sim-engine/src/components/mod.rs"

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_node_entry,node_node_store,node_node_canvas,node_node_nodes,node_node_zones,node_node_particles,node_node_palette,node_node_toolbar,node_node_controls,node_node_chaos,node_node_blueprints,node_node_properties,node_node_edgeprops,node_node_metrics,node_node_status,node_node_report,node_node_controller,node_node_wasm toneBlue
class node_node_engine,node_node_chaoscore,node_node_cost,node_node_components toneAmber
class node_node_icondata,node_node_icons toneMint
```

## Components

### Web app

Client-side React application for editing diagrams and running simulations.

- [App shell](https://github.com/raghukr80/syssim/blob/main/apps/web/src/main.tsx): Vite/React entry · Bootstraps the single-page client application. · `apps/web/src/main.tsx`
- [Diagram store](https://github.com/raghukr80/syssim/blob/main/apps/web/src/stores/diagramStore.ts): Zustand state · Central model for diagram data, selection, simulation state, and UI coordination. · `apps/web/src/stores/diagramStore.ts`
- [Canvas editor](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/canvas/SimulatorCanvas.tsx): React Flow canvas · Renders and edits the system diagram, nodes, edges, zones, and traffic visuals. · `apps/web/src/components/canvas/SimulatorCanvas.tsx`
- [Node views](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/canvas/ComponentNode.tsx): Canvas primitives · Node and group renderers used by the graph editor. · `apps/web/src/components/canvas/ComponentNode.tsx`
- [Layout zones](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/canvas/LayoutZones.tsx): Canvas overlay · Placement and container geometry for diagram structure. · `apps/web/src/components/canvas/LayoutZones.tsx`
- [Traffic viz](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/canvas/ParticleCanvas.tsx): Canvas effect · Animated flow and simulation visualization layered over the canvas. · `apps/web/src/components/canvas/ParticleCanvas.tsx`
- [Component palette](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/palette/ComponentPalette.tsx): Catalog UI · Drag-and-drop component library for building diagrams. · `apps/web/src/components/palette/ComponentPalette.tsx`
- [Command bar](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/toolbar/Toolbar.tsx): Workflow controls · Top-level controls for simulation, chaos, blueprints, and cost views. · `apps/web/src/components/toolbar/Toolbar.tsx`
- [Simulation controls](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/toolbar/SimulationControls.tsx): Run controls · Play, stop, speed, and traffic controls that drive the simulation state. · `apps/web/src/components/toolbar/SimulationControls.tsx`
- [Chaos panel](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/toolbar/ChaosPanel.tsx): Scenario UI · Selects and applies failure scenarios to diagram targets. · `apps/web/src/components/toolbar/ChaosPanel.tsx`
- [Blueprint panel](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/toolbar/BlueprintPanel.tsx): Template UI · Imports, exports, and applies reusable diagram templates. · `apps/web/src/components/toolbar/BlueprintPanel.tsx`
- [Properties pane](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/properties/PropertiesPanel.tsx): Inspector UI · Edits node metadata, capacity settings, and visual identity. · `apps/web/src/components/properties/PropertiesPanel.tsx`
- [Edge editor](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/properties/EdgePropertiesPanel.tsx): Inspector UI · Edits connection metadata and edge behavior. · `apps/web/src/components/properties/EdgePropertiesPanel.tsx`
- [Metrics panel](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/metrics/MetricsPanel.tsx): Observability UI · Shows throughput, latency, errors, utilization, and other live results. · `apps/web/src/components/metrics/MetricsPanel.tsx`
- [Status bar](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/metrics/StatusBar.tsx): Live summary · Compact simulation status and health readout. · `apps/web/src/components/metrics/StatusBar.tsx`
- [Report modal](https://github.com/raghukr80/syssim/blob/main/apps/web/src/components/metrics/ReportModal.tsx): Export UI · Presents simulation reports and incident summaries. · `apps/web/src/components/metrics/ReportModal.tsx`
- [Sim controller](https://github.com/raghukr80/syssim/blob/main/apps/web/src/wasm/simulationController.ts): WASM bridge · Connects the web app state and UI to the simulation runtime. · `apps/web/src/wasm/simulationController.ts`
- [WASM module](https://github.com/raghukr80/syssim/blob/main/apps/web/src/wasm/sim_engine.js): Generated bindings · Compiled simulation engine and generated JavaScript/WASM bindings. · `apps/web/src/wasm/sim_engine.js`

### Simulation engine

Optional Rust/WASM compute layer for simulation and chaos modeling.

- [Rust engine](https://github.com/raghukr80/syssim/blob/main/packages/sim-engine/src/engine.rs): Simulation core · Core simulation, chaos, cost, and component behavior logic. · `packages/sim-engine/src/engine.rs`
- [Chaos logic](https://github.com/raghukr80/syssim/blob/main/packages/sim-engine/src/chaos.rs): Engine module · Failure injection and scenario effects inside the simulation runtime. · `packages/sim-engine/src/chaos.rs`
- [Cost model](https://github.com/raghukr80/syssim/blob/main/packages/sim-engine/src/cost.rs): Engine module · Economic and resource accounting for simulated systems. · `packages/sim-engine/src/cost.rs`
- [Component models](https://github.com/raghukr80/syssim/blob/main/packages/sim-engine/src/components/mod.rs): Engine module · Typed behavior profiles for simulated diagram components. · `packages/sim-engine/src/components/mod.rs`

### Assets and data

Static icon catalog, manifests, and exported report artifacts.

- [Icon catalog](https://github.com/raghukr80/syssim/blob/main/apps/web/src/data/icons.ts): Asset manifest · Local icon metadata used by the palette and icon picker. · `apps/web/src/data/icons.ts`
- [SVG library](https://github.com/raghukr80/syssim/tree/main/apps/web/public/icons): Static assets · Cloud and technology icon sets bundled with the app. · `apps/web/public/icons`

## Connections

- App shell → Diagram store: initializes · App shell creates and wires the shared diagram state.
- App shell → Canvas editor: renders · Main application surface contains the canvas editor.
- App shell → Command bar: mounts · The shell hosts operational controls.
- App shell → Metrics panel: mounts · The shell hosts metrics and reporting views.
- Diagram store → Canvas editor: feeds · Canvas reads and writes diagram state.
- Diagram store → Component palette: feeds · Palette reads catalog and creation state.
- Diagram store → Properties pane: feeds · Inspector panels edit the shared model.
- Diagram store → Edge editor: feeds · Edge inspector updates connection metadata.
- Diagram store → Simulation controls: drives · Run controls mutate simulation state.
- Diagram store → Chaos panel: drives · Chaos actions update active injections and targets.
- Diagram store → Blueprint panel: serializes · Blueprint actions operate on the same diagram model.
- Canvas editor → Node views: composes · Canvas uses node and group renderers.
- Canvas editor → Layout zones: layers · Canvas overlays structural zones.
- Canvas editor → Traffic viz: layers · Canvas overlays traffic and activity effects.
- Component palette → Icon catalog: uses · Palette and icon picker are driven by icon metadata.
- Icon catalog → SVG library: indexes · Manifest maps to local SVG assets.
- Command bar → Simulation controls: contains · Primary run controls live in the command bar.
- Command bar → Chaos panel: contains · Chaos scenario controls live in the command bar.
- Command bar → Blueprint panel: contains · Template workflows are exposed in the command bar.
- Properties pane → Diagram store: updates · Property edits flow back into the shared model.
- Edge editor → Diagram store: updates · Edge metadata edits flow back into the shared model.
- Sim controller → Diagram store: reads · Controller consumes diagram and simulation state.
- Sim controller → WASM module: calls · Controller invokes the simulation runtime bindings.
- WASM module → Rust engine: bridges · Generated bindings expose the Rust engine to the client.
- Rust engine → Chaos logic: includes · Engine contains chaos and failure injection logic.
- Rust engine → Cost model: includes · Engine contains cost and resource modeling logic.
- Rust engine → Component models: includes · Engine contains behavior models for component types.
- WASM module → Metrics panel: feeds · Simulation output drives metrics panels and status views.
- WASM module → Report modal: feeds · Simulation output is summarized in downloadable reports.