# newton-school/systems-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/newton-school/systems-simulator
- Repository: https://github.com/newton-school/systems-simulator

## Overview

NS System Design Simulator is a visual distributed-system modeling and discrete-event simulation application, available as a browser app and Electron desktop shell. The primary workflow is to build and configure a topology, run it in a worker, then inspect aggregate, per-node, bottleneck, and replay results before iterating. It also includes question authoring and evaluation capabilities, plus a CLI for scripted runs. README-described workflow links are cited; some internal engine and authoring relationships are only loosely supported by the sampled excerpts, so those links are dashed or omitted.

Main entry points: [`src/engine/engine.ts`](https://github.com/newton-school/systems-simulator/blob/master/src/engine/engine.ts) (DES engine), [`src/engine/worker/simulation.worker.ts`](https://github.com/newton-school/systems-simulator/blob/master/src/engine/worker/simulation.worker.ts) (Simulation worker), [`src/cli/index.ts`](https://github.com/newton-school/systems-simulator/blob/master/src/cli/index.ts) (Scripted CLI), [`src/engine/validation/validator.ts`](https://github.com/newton-school/systems-simulator/blob/master/src/engine/validation/validator.ts) (Topology validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build and configure"]
  node_canvas["Topology canvas<br/>[FlowCanvas.tsx]"]
  node_library["Component library<br/>[LibrarySidebar.tsx]"]
  node_store["Topology state<br/>[useStore.ts]"]
  node_properties["Node properties"]
  node_filehandlers["Topology files<br/>[useFileHandlers.ts]"]
end

subgraph group_simulation["Simulation runtime"]
  node_controls["Simulation controls"]
  node_serializer["Topology serializer"]
  node_validation["Topology validator<br/>[validator.ts]"]
  node_worker["Simulation worker"]
  node_engine["DES engine<br/>[engine.ts]"]
  node_nodequeue["G/G/c/K queues<br/>[GGcKNode.ts]"]
  node_routing["Request routing<br/>[routing.ts]"]
end

subgraph group_analysis["Results and analysis"]
  node_metrics["Metrics and replay<br/>[metrics.ts]"]
  node_output["Simulation output<br/>[output.ts]"]
  node_results["Results tray<br/>[ResultsTray.tsx]"]
end

subgraph group_authoring["Question authoring"]
  node_questionstudio["Question studio"]
  node_questioncompiler["Question compiler"]
  node_questionproject["Question project"]
  node_evaluation["Question evaluation<br/>[evaluate.ts]"]
end

subgraph group_interfaces["Desktop and CLI"]
  node_fileservice["File service<br/>[FileService.web.ts]"]
  node_cli["Scripted CLI<br/>[index.ts]"]
end

node_user(("System designer"))

node_user -->|"selects components"| node_library
node_library -->|"adds nodes"| node_canvas
node_canvas -->|"updates topology"| node_store
node_user -->|"configures nodes"| node_properties
node_properties -->|"updates configuration"| node_store
node_user -->|"saves or opens"| node_filehandlers
node_filehandlers -->|"loads or saves"| node_fileservice
node_user -->|"starts a run"| node_controls
node_controls -->|"requests topology"| node_serializer
node_serializer -->|"validates topology"| node_validation
node_validation -->|"sends topology"| node_worker
node_worker -->|"runs simulation"| node_engine
node_engine -.->|"processes requests"| node_nodequeue
node_engine -.->|"resolves routes"| node_routing
node_engine -.->|"collects metrics"| node_metrics
node_engine -->|"generates output"| node_output
node_worker -->|"returns run results"| node_results
node_results -->|"shows analysis"| node_user
node_user -.->|"authors questions"| node_questionstudio
node_questionstudio -.->|"edits project"| node_questionproject
node_questionproject -.->|"compiles package"| node_questioncompiler
node_questioncompiler -.->|"prepares evaluation"| node_evaluation
node_user -->|"runs scripted jobs"| node_cli
node_cli -->|"validates topology"| node_validation
node_cli -->|"runs simulation"| node_engine

click node_canvas "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/canvas/FlowCanvas.tsx"
click node_library "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/library/LibrarySidebar.tsx"
click node_store "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/store/useStore.ts"
click node_properties "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/properties/PropertiesPanel.tsx"
click node_filehandlers "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/hooks/useFileHandlers.ts"
click node_fileservice "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/services/FileService.web.ts"
click node_controls "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/simulation/SimulationControls.tsx"
click node_serializer "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/hooks/useTopologySerializer.ts"
click node_validation "https://github.com/newton-school/systems-simulator/blob/master/src/engine/validation/validator.ts"
click node_worker "https://github.com/newton-school/systems-simulator/blob/master/src/engine/worker/simulation.worker.ts"
click node_engine "https://github.com/newton-school/systems-simulator/blob/master/src/engine/engine.ts"
click node_nodequeue "https://github.com/newton-school/systems-simulator/blob/master/src/engine/nodes/GGcKNode.ts"
click node_routing "https://github.com/newton-school/systems-simulator/blob/master/src/engine/routing.ts"
click node_metrics "https://github.com/newton-school/systems-simulator/blob/master/src/engine/metrics.ts"
click node_output "https://github.com/newton-school/systems-simulator/blob/master/src/engine/analysis/output.ts"
click node_results "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/simulation/ResultsTray.tsx"
click node_questionstudio "https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/authoring/QuestionStudioShell.tsx"
click node_questioncompiler "https://github.com/newton-school/systems-simulator/blob/master/src/engine/analysis/questionAuthoringCompiler.ts"
click node_questionproject "https://github.com/newton-school/systems-simulator/blob/master/src/engine/analysis/questionAuthoringProject.ts"
click node_evaluation "https://github.com/newton-school/systems-simulator/blob/master/src/engine/analysis/evaluate.ts"
click node_cli "https://github.com/newton-school/systems-simulator/blob/master/src/cli/index.ts"

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_canvas,node_library,node_store,node_properties,node_filehandlers toneBlue
class node_controls,node_serializer,node_validation,node_worker,node_engine,node_nodequeue,node_routing toneAmber
class node_metrics,node_output,node_results toneMint
class node_questionstudio,node_questioncompiler,node_questionproject,node_evaluation toneRose
class node_fileservice,node_cli,node_user toneIndigo
```

## Components

### Build and configure

- [Topology canvas](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/canvas/FlowCanvas.tsx): `src/renderer/src/components/canvas/FlowCanvas.tsx`
- [Component library](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/library/LibrarySidebar.tsx): `src/renderer/src/components/library/LibrarySidebar.tsx`
- [Topology state](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/store/useStore.ts): `src/renderer/src/store/useStore.ts`
- [Node properties](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/properties/PropertiesPanel.tsx): `src/renderer/src/components/properties/PropertiesPanel.tsx`
- [Topology files](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/hooks/useFileHandlers.ts): `src/renderer/src/hooks/useFileHandlers.ts`

### Simulation runtime

- [Simulation controls](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/simulation/SimulationControls.tsx): `src/renderer/src/components/simulation/SimulationControls.tsx`
- [Topology serializer](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/hooks/useTopologySerializer.ts): `src/renderer/src/hooks/useTopologySerializer.ts`
- [Topology validator](https://github.com/newton-school/systems-simulator/blob/master/src/engine/validation/validator.ts): `src/engine/validation/validator.ts`
- [Simulation worker](https://github.com/newton-school/systems-simulator/blob/master/src/engine/worker/simulation.worker.ts): `src/engine/worker/simulation.worker.ts`
- [DES engine](https://github.com/newton-school/systems-simulator/blob/master/src/engine/engine.ts): `src/engine/engine.ts`
- [G/G/c/K queues](https://github.com/newton-school/systems-simulator/blob/master/src/engine/nodes/GGcKNode.ts): `src/engine/nodes/GGcKNode.ts`
- [Request routing](https://github.com/newton-school/systems-simulator/blob/master/src/engine/routing.ts): `src/engine/routing.ts`

### Results and analysis

- [Metrics and replay](https://github.com/newton-school/systems-simulator/blob/master/src/engine/metrics.ts): `src/engine/metrics.ts`
- [Simulation output](https://github.com/newton-school/systems-simulator/blob/master/src/engine/analysis/output.ts): `src/engine/analysis/output.ts`
- [Results tray](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/simulation/ResultsTray.tsx): `src/renderer/src/components/simulation/ResultsTray.tsx`

### Question authoring

- [Question studio](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/components/authoring/QuestionStudioShell.tsx): `src/renderer/src/components/authoring/QuestionStudioShell.tsx`
- [Question compiler](https://github.com/newton-school/systems-simulator/blob/master/src/engine/analysis/questionAuthoringCompiler.ts): `src/engine/analysis/questionAuthoringCompiler.ts`
- [Question project](https://github.com/newton-school/systems-simulator/blob/master/src/engine/analysis/questionAuthoringProject.ts): `src/engine/analysis/questionAuthoringProject.ts`
- [Question evaluation](https://github.com/newton-school/systems-simulator/blob/master/src/engine/analysis/evaluate.ts): `src/engine/analysis/evaluate.ts`

### Desktop and CLI

- [File service](https://github.com/newton-school/systems-simulator/blob/master/src/renderer/src/services/FileService.web.ts): `src/renderer/src/services/FileService.web.ts`
- [Scripted CLI](https://github.com/newton-school/systems-simulator/blob/master/src/cli/index.ts): `src/cli/index.ts`

### Other components

- **System designer**

## Connections

- System designer → Component library: selects components (evidence: `README.md`)
- Component library → Topology canvas: adds nodes (evidence: `README.md`)
- Topology canvas → Topology state: updates topology (evidence: `README.md`)
- System designer → Node properties: configures nodes (evidence: `README.md`)
- Node properties → Topology state: updates configuration (evidence: `README.md`)
- System designer → Topology files: saves or opens (evidence: `README.md`)
- Topology files → File service: loads or saves (evidence: `src/renderer/src/hooks/useFileHandlers.ts`)
- System designer → Simulation controls: starts a run (evidence: `README.md`)
- Simulation controls → Topology serializer: requests topology (evidence: `README.md`)
- Topology serializer → Topology validator: validates topology (evidence: `README.md`)
- Topology validator → Simulation worker: sends topology (evidence: `README.md`)
- Simulation worker → DES engine: runs simulation (evidence: `src/engine/worker/simulation.worker.ts`)
- DES engine → G/G/c/K queues: processes requests (evidence: `src/engine/engine.ts`)
- DES engine → Request routing: resolves routes (evidence: `src/engine/engine.ts`)
- DES engine → Metrics and replay: collects metrics (evidence: `src/engine/engine.ts`)
- DES engine → Simulation output: generates output (evidence: `src/engine/engine.ts`)
- Simulation worker → Results tray: returns run results (evidence: `README.md`)
- Results tray → System designer: shows analysis (evidence: `README.md`)
- System designer → Question studio: authors questions
- Question studio → Question project: edits project
- Question project → Question compiler: compiles package
- Question compiler → Question evaluation: prepares evaluation
- System designer → Scripted CLI: runs scripted jobs (evidence: `README.md`)
- Scripted CLI → Topology validator: validates topology (evidence: `src/cli/index.ts`)
- Scripted CLI → DES engine: runs simulation (evidence: `src/cli/index.ts`)
