# nezaal/symsim architecture

> Architecture diagram of the GitHub repository nezaal/symsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nezaal/symsim
- Repository: https://github.com/nezaal/symsim

## Overview

SystemSim is a visual system-architecture editor and discrete-event simulator. Users assemble and configure a component graph, run it with chosen duration and seed, and inspect results; designs can also be autosaved, versioned, and shared. The graph separates editor state, simulation execution, project/auth services, and presentation. Sampled excerpts establish several key calls; some UI, persistence, and result relationships are included only where the source index names the dependency, so unsampled wiring is not inferred.

Main entry points: [`frontend/src/store/architectureStore.js`](https://github.com/nezaal/symsim/blob/main/frontend/src/store/architectureStore.js) (Architecture state), [`frontend/src/store/projectStore.js`](https://github.com/nezaal/symsim/blob/main/frontend/src/store/projectStore.js) (Project state), [`frontend/src/hooks/useRunPersistence.js`](https://github.com/nezaal/symsim/blob/main/frontend/src/hooks/useRunPersistence.js) (Run persistence), [`frontend/src/App.jsx`](https://github.com/nezaal/symsim/blob/main/frontend/src/App.jsx) (App routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Product experience"]
  node_app["App routing<br/>[App.jsx]"]
  node_landing["Landing and templates<br/>[LandingPage.jsx]"]
  node_editor["Editor page<br/>[EditorPage.jsx]"]
  node_runcontrols["Run controls<br/>[RunControls.jsx]"]
  node_results["Results and charts<br/>[ResultsOverlay.jsx]"]
  node_shared["Shared design page<br/>[SharedPage.jsx]"]
end

subgraph group_design["Design editing"]
  node_canvas["Canvas and palette<br/>[CanvasArea.jsx]"]
  node_settings["Component settings<br/>[NodeSettings.jsx]"]
  node_architecture["Architecture state"]
end

subgraph group_simulation["Simulation engine"]
  node_componentdefs["Component definitions<br/>[componentTypes.ts]"]
  node_graphrules["Graph validation<br/>[graphRules.ts]"]
  node_simstate["Simulation state<br/>[simulationStore.js]"]
  node_worker["Simulation worker"]
  node_compiler["Graph compilation<br/>[compile.ts]"]
  node_simulator["Event simulation<br/>[simulator.ts]"]
  node_stations["Service models<br/>[stations.ts]"]
  node_resources["Resource queues<br/>[resources.ts]"]
  node_metrics["Run metrics<br/>[metrics.ts]"]
end

subgraph group_projects["Projects and identity"]
  node_projectstate["Project state<br/>[projectStore.js]"]
  node_projectapi["Projects API<br/>[projectsApi.js]"]
  node_auth["Authentication state<br/>[authStore.js]"]
  node_supabase[("Supabase services<br/>[supabase.js]")]
  node_runapi["Run storage API<br/>[projectsApi.js]"]
end

subgraph group_persistence["Design and run storage"]
  node_session["Editor session"]
  node_draft[("Browser draft<br/>[draftStorage.js]")]
  node_snapshot["Graph snapshots<br/>[graphSnapshot.js]"]
  node_runpersistence["Run persistence"]
end

node_user(("Designer"))

node_user -->|"opens"| node_app
node_app -->|"routes to"| node_landing
node_app -->|"routes to"| node_editor
node_app -->|"routes to"| node_shared
node_landing -->|"reads definitions"| node_componentdefs
node_editor -.->|"presents"| node_canvas
node_canvas -.->|"edits graph"| node_architecture
node_settings -.->|"updates config"| node_architecture
node_architecture -->|"validates settings"| node_componentdefs
node_architecture -->|"checks connections"| node_graphrules
node_user -->|"starts run"| node_runcontrols
node_runcontrols -->|"reads graph"| node_architecture
node_runcontrols -->|"starts simulation"| node_simstate
node_simstate -->|"submits graph"| node_compiler
node_worker -->|"uses engine"| node_compiler
node_compiler -.->|"builds model"| node_simulator
node_simulator -->|"dispatches requests"| node_stations
node_stations -->|"uses resources"| node_resources
node_simulator -->|"collects metrics"| node_metrics
node_simstate -.->|"provides run state"| node_results
node_editor -.->|"restores session"| node_session
node_session -->|"loads and saves"| node_draft
node_draft -->|"serializes graph"| node_snapshot
node_session -->|"opens project"| node_projectstate
node_projectstate -->|"loads and saves"| node_projectapi
node_projectstate -->|"serializes graph"| node_snapshot
node_projectstate -->|"replaces graph"| node_architecture
node_projectapi -->|"uses client"| node_supabase
node_auth -->|"authenticates"| node_supabase
node_shared -->|"loads shared design"| node_projectapi
node_shared -->|"deserializes graph"| node_snapshot
node_runpersistence -->|"saves completed run"| node_projectapi
node_runpersistence -->|"reads run state"| node_simstate
node_runpersistence -->|"checks version"| node_projectstate
node_runpersistence -->|"checks identity"| node_auth

click node_app "https://github.com/nezaal/symsim/blob/main/frontend/src/App.jsx"
click node_landing "https://github.com/nezaal/symsim/blob/main/frontend/src/pages/LandingPage.jsx"
click node_editor "https://github.com/nezaal/symsim/blob/main/frontend/src/pages/EditorPage.jsx"
click node_canvas "https://github.com/nezaal/symsim/blob/main/frontend/src/components/CanvasArea.jsx"
click node_settings "https://github.com/nezaal/symsim/blob/main/frontend/src/components/NodeSettings.jsx"
click node_architecture "https://github.com/nezaal/symsim/blob/main/frontend/src/store/architectureStore.js"
click node_componentdefs "https://github.com/nezaal/symsim/blob/main/packages/engine/src/componentTypes.ts"
click node_graphrules "https://github.com/nezaal/symsim/blob/main/packages/engine/src/graphRules.ts"
click node_runcontrols "https://github.com/nezaal/symsim/blob/main/frontend/src/components/RunControls.jsx"
click node_simstate "https://github.com/nezaal/symsim/blob/main/frontend/src/store/simulationStore.js"
click node_worker "https://github.com/nezaal/symsim/blob/main/frontend/src/worker/simulation.worker.js"
click node_compiler "https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/compile.ts"
click node_simulator "https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/simulator.ts"
click node_stations "https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/stations.ts"
click node_resources "https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/resources.ts"
click node_metrics "https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/metrics.ts"
click node_results "https://github.com/nezaal/symsim/blob/main/frontend/src/components/results/ResultsOverlay.jsx"
click node_session "https://github.com/nezaal/symsim/blob/main/frontend/src/hooks/useEditorSession.js"
click node_draft "https://github.com/nezaal/symsim/blob/main/frontend/src/lib/draftStorage.js"
click node_snapshot "https://github.com/nezaal/symsim/blob/main/frontend/src/lib/graphSnapshot.js"
click node_projectstate "https://github.com/nezaal/symsim/blob/main/frontend/src/store/projectStore.js"
click node_projectapi "https://github.com/nezaal/symsim/blob/main/frontend/src/lib/projectsApi.js"
click node_auth "https://github.com/nezaal/symsim/blob/main/frontend/src/store/authStore.js"
click node_supabase "https://github.com/nezaal/symsim/blob/main/frontend/src/lib/supabase.js"
click node_shared "https://github.com/nezaal/symsim/blob/main/frontend/src/pages/SharedPage.jsx"
click node_runpersistence "https://github.com/nezaal/symsim/blob/main/frontend/src/hooks/useRunPersistence.js"
click node_runapi "https://github.com/nezaal/symsim/blob/main/frontend/src/lib/projectsApi.js"

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,node_landing,node_editor,node_runcontrols,node_results,node_shared toneBlue
class node_canvas,node_settings,node_architecture toneAmber
class node_componentdefs,node_graphrules,node_simstate,node_worker,node_compiler,node_simulator,node_stations,node_resources,node_metrics toneMint
class node_projectstate,node_projectapi,node_auth,node_supabase,node_runapi toneRose
class node_session,node_draft,node_snapshot,node_runpersistence,node_user toneIndigo
```

## Components

### Product experience

- [App routing](https://github.com/nezaal/symsim/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Landing and templates](https://github.com/nezaal/symsim/blob/main/frontend/src/pages/LandingPage.jsx): `frontend/src/pages/LandingPage.jsx`
- [Editor page](https://github.com/nezaal/symsim/blob/main/frontend/src/pages/EditorPage.jsx): `frontend/src/pages/EditorPage.jsx`
- [Run controls](https://github.com/nezaal/symsim/blob/main/frontend/src/components/RunControls.jsx): `frontend/src/components/RunControls.jsx`
- [Results and charts](https://github.com/nezaal/symsim/blob/main/frontend/src/components/results/ResultsOverlay.jsx): `frontend/src/components/results/ResultsOverlay.jsx`
- [Shared design page](https://github.com/nezaal/symsim/blob/main/frontend/src/pages/SharedPage.jsx): `frontend/src/pages/SharedPage.jsx`

### Design editing

- [Canvas and palette](https://github.com/nezaal/symsim/blob/main/frontend/src/components/CanvasArea.jsx): `frontend/src/components/CanvasArea.jsx`
- [Component settings](https://github.com/nezaal/symsim/blob/main/frontend/src/components/NodeSettings.jsx): `frontend/src/components/NodeSettings.jsx`
- [Architecture state](https://github.com/nezaal/symsim/blob/main/frontend/src/store/architectureStore.js): `frontend/src/store/architectureStore.js`

### Simulation engine

- [Component definitions](https://github.com/nezaal/symsim/blob/main/packages/engine/src/componentTypes.ts): `packages/engine/src/componentTypes.ts`
- [Graph validation](https://github.com/nezaal/symsim/blob/main/packages/engine/src/graphRules.ts): `packages/engine/src/graphRules.ts`
- [Simulation state](https://github.com/nezaal/symsim/blob/main/frontend/src/store/simulationStore.js): `frontend/src/store/simulationStore.js`
- [Simulation worker](https://github.com/nezaal/symsim/blob/main/frontend/src/worker/simulation.worker.js): `frontend/src/worker/simulation.worker.js`
- [Graph compilation](https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/compile.ts): `packages/engine/src/sim/compile.ts`
- [Event simulation](https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/simulator.ts): `packages/engine/src/sim/simulator.ts`
- [Service models](https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/stations.ts): `packages/engine/src/sim/stations.ts`
- [Resource queues](https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/resources.ts): `packages/engine/src/sim/resources.ts`
- [Run metrics](https://github.com/nezaal/symsim/blob/main/packages/engine/src/sim/metrics.ts): `packages/engine/src/sim/metrics.ts`

### Projects and identity

- [Project state](https://github.com/nezaal/symsim/blob/main/frontend/src/store/projectStore.js): `frontend/src/store/projectStore.js`
- [Projects API](https://github.com/nezaal/symsim/blob/main/frontend/src/lib/projectsApi.js): `frontend/src/lib/projectsApi.js`
- [Authentication state](https://github.com/nezaal/symsim/blob/main/frontend/src/store/authStore.js): `frontend/src/store/authStore.js`
- [Supabase services](https://github.com/nezaal/symsim/blob/main/frontend/src/lib/supabase.js): `frontend/src/lib/supabase.js`
- [Run storage API](https://github.com/nezaal/symsim/blob/main/frontend/src/lib/projectsApi.js): `frontend/src/lib/projectsApi.js`

### Design and run storage

- [Editor session](https://github.com/nezaal/symsim/blob/main/frontend/src/hooks/useEditorSession.js): `frontend/src/hooks/useEditorSession.js`
- [Browser draft](https://github.com/nezaal/symsim/blob/main/frontend/src/lib/draftStorage.js): `frontend/src/lib/draftStorage.js`
- [Graph snapshots](https://github.com/nezaal/symsim/blob/main/frontend/src/lib/graphSnapshot.js): `frontend/src/lib/graphSnapshot.js`
- [Run persistence](https://github.com/nezaal/symsim/blob/main/frontend/src/hooks/useRunPersistence.js): `frontend/src/hooks/useRunPersistence.js`

### Other components

- **Designer**

## Connections

- Designer → App routing: opens (evidence: `frontend/src/App.jsx`)
- App routing → Landing and templates: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Editor page: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Shared design page: routes to (evidence: `frontend/src/App.jsx`)
- Landing and templates → Component definitions: reads definitions (evidence: `frontend/src/pages/LandingPage.jsx`)
- Editor page → Canvas and palette: presents
- Canvas and palette → Architecture state: edits graph
- Component settings → Architecture state: updates config
- Architecture state → Component definitions: validates settings (evidence: `frontend/src/store/architectureStore.js`)
- Architecture state → Graph validation: checks connections (evidence: `frontend/src/store/architectureStore.js`)
- Designer → Run controls: starts run (evidence: `frontend/src/components/RunControls.jsx`)
- Run controls → Architecture state: reads graph (evidence: `frontend/src/components/RunControls.jsx`)
- Run controls → Simulation state: starts simulation (evidence: `frontend/src/components/RunControls.jsx`)
- Simulation state → Graph compilation: submits graph (evidence: `frontend/src/store/simulationStore.js`)
- Simulation worker → Graph compilation: uses engine (evidence: `frontend/src/worker/simulation.worker.js`)
- Graph compilation → Event simulation: builds model
- Event simulation → Service models: dispatches requests (evidence: `packages/engine/src/sim/simulator.ts`)
- Service models → Resource queues: uses resources (evidence: `packages/engine/src/sim/stations.ts`)
- Event simulation → Run metrics: collects metrics (evidence: `packages/engine/src/sim/simulator.ts`)
- Simulation state → Results and charts: provides run state
- Editor page → Editor session: restores session
- Editor session → Browser draft: loads and saves (evidence: `frontend/src/hooks/useEditorSession.js`)
- Browser draft → Graph snapshots: serializes graph (evidence: `frontend/src/lib/draftStorage.js`)
- Editor session → Project state: opens project (evidence: `frontend/src/hooks/useEditorSession.js`)
- Project state → Projects API: loads and saves (evidence: `frontend/src/store/projectStore.js`)
- Project state → Graph snapshots: serializes graph (evidence: `frontend/src/store/projectStore.js`)
- Project state → Architecture state: replaces graph (evidence: `frontend/src/store/projectStore.js`)
- Projects API → Supabase services: uses client (evidence: `frontend/src/lib/projectsApi.js`)
- Authentication state → Supabase services: authenticates (evidence: `frontend/src/store/authStore.js`)
- Shared design page → Projects API: loads shared design (evidence: `frontend/src/pages/SharedPage.jsx`)
- Shared design page → Graph snapshots: deserializes graph (evidence: `frontend/src/pages/SharedPage.jsx`)
- Run persistence → Projects API: saves completed run (evidence: `frontend/src/hooks/useRunPersistence.js`)
- Run persistence → Simulation state: reads run state (evidence: `frontend/src/hooks/useRunPersistence.js`)
- Run persistence → Project state: checks version (evidence: `frontend/src/hooks/useRunPersistence.js`)
- Run persistence → Authentication state: checks identity (evidence: `frontend/src/hooks/useRunPersistence.js`)
