# khp-informatics/patient-flow-simulator architecture

> Architecture diagram of the GitHub repository khp-informatics/patient-flow-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khp-informatics/patient-flow-simulator
- Repository: https://github.com/khp-informatics/patient-flow-simulator

## Overview

Patient Flow Simulator is a standalone teaching web application for configuring and running a simulated hospital, then examining patient waits, ward occupancy, resource use and transfer-network bottlenecks. The principal workflow is management configuration and run controls → patient generation and ward-based simulation → performance history and analysis. The README also documents repeatable preset-patient experiments and saving/loading configurations. The sampled source shows the simulation controller and core model; some UI wiring and analysis implementations are represented by the documented capabilities and their source paths.

Main entry points: [`src/interactive_simulation.js`](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/interactive_simulation.js) (Simulation loop), [`index.html`](https://github.com/khp-informatics/patient-flow-simulator/blob/master/index.html) (Results dashboard), [`src/Simulation.js`](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/Simulation.js) (Ward and queues), [`src/plot.js`](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/plot.js) (Performance charts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Hospital setup"]
  node_ward_config["Ward definitions"]
  node_virtual_wards["Pool and Exit<br/>[virtual_wards.js]"]
  node_patient_config["Patient scenarios"]
  node_simulation_config["Run settings"]
end

subgraph group_engine["Simulation engine"]
  node_sim_controller["Simulation loop"]
  node_patient_model["Patient model<br/>[Simulation.js]"]
  node_ward_model["Ward and queues<br/>[Simulation.js]"]
  node_patient_generator["Patient generation<br/>[Simulation.js]"]
  node_priority_queue["Priority queue"]
end

subgraph group_analysis["Performance analysis"]
  node_run_history["Simulation history"]
  node_metrics["Wait and score metrics<br/>[Simulation.js]"]
  node_plots["Performance charts<br/>[plot.js]"]
  node_network["Transfer network analysis<br/>[graph.js]"]
end

subgraph group_interaction["User controls"]
  node_controls["Run and configure"]
  node_config_files["Saved configurations"]
  node_dashboard["Results dashboard<br/>[index.html]"]
end

node_manager(("Hospital manager"))

node_manager -->|"sets options"| node_controls
node_controls -->|"edits wards"| node_ward_config
node_controls -->|"selects patients"| node_patient_config
node_controls -->|"sets run mode"| node_simulation_config
node_controls -->|"starts or pauses"| node_sim_controller
node_sim_controller -->|"requests arrivals"| node_patient_generator
node_patient_generator -->|"creates patients"| node_patient_model
node_sim_controller -->|"admits and transfers"| node_ward_model
node_sim_controller -->|"initializes wards"| node_virtual_wards
node_sim_controller -->|"initializes wards"| node_ward_config
node_ward_model -->|"orders queues"| node_priority_queue
node_sim_controller -->|"records runs"| node_run_history
node_sim_controller -->|"summarizes patients"| node_metrics
node_sim_controller -->|"plots results"| node_plots
node_sim_controller -->|"builds transfer graph"| node_network
node_run_history -->|"shows history"| node_dashboard
node_plots -->|"renders charts"| node_dashboard
node_network -->|"shows network analysis"| node_dashboard
node_metrics -->|"shows performance"| node_dashboard
node_controls -->|"imports or exports"| node_config_files
node_manager -->|"reviews results"| node_dashboard

click node_controls "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/interactive_simulation.js"
click node_ward_config "https://github.com/khp-informatics/patient-flow-simulator/tree/master/src/config"
click node_virtual_wards "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/config/virtual_wards.js"
click node_patient_config "https://github.com/khp-informatics/patient-flow-simulator/tree/master/src/config"
click node_simulation_config "https://github.com/khp-informatics/patient-flow-simulator/tree/master/src/config"
click node_sim_controller "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/interactive_simulation.js"
click node_patient_model "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/Simulation.js"
click node_ward_model "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/Simulation.js"
click node_patient_generator "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/Simulation.js"
click node_priority_queue "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/lib/FastPriorityQueue.js"
click node_run_history "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/interactive_simulation.js"
click node_metrics "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/Simulation.js"
click node_plots "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/plot.js"
click node_network "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/graph.js"
click node_config_files "https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/interactive_simulation.js"
click node_dashboard "https://github.com/khp-informatics/patient-flow-simulator/blob/master/index.html"

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_ward_config,node_virtual_wards,node_patient_config,node_simulation_config toneBlue
class node_sim_controller,node_patient_model,node_ward_model,node_patient_generator,node_priority_queue toneAmber
class node_run_history,node_metrics,node_plots,node_network toneMint
class node_controls,node_config_files,node_dashboard toneRose
class node_manager toneIndigo
```

## Components

### Hospital setup

- [Ward definitions](https://github.com/khp-informatics/patient-flow-simulator/tree/master/src/config): `src/config`
- [Pool and Exit](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/config/virtual_wards.js): `src/config/virtual_wards.js`
- [Patient scenarios](https://github.com/khp-informatics/patient-flow-simulator/tree/master/src/config): `src/config`
- [Run settings](https://github.com/khp-informatics/patient-flow-simulator/tree/master/src/config): `src/config`

### Simulation engine

- [Simulation loop](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/interactive_simulation.js): `src/interactive_simulation.js`
- [Patient model](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/Simulation.js): `src/Simulation.js`
- [Ward and queues](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/Simulation.js): `src/Simulation.js`
- [Patient generation](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/Simulation.js): `src/Simulation.js`
- [Priority queue](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/lib/FastPriorityQueue.js): `src/lib/FastPriorityQueue.js`

### Performance analysis

- [Simulation history](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/interactive_simulation.js): `src/interactive_simulation.js`
- [Wait and score metrics](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/Simulation.js): `src/Simulation.js`
- [Performance charts](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/plot.js): `src/plot.js`
- [Transfer network analysis](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/graph.js): `src/graph.js`

### User controls

- [Run and configure](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/interactive_simulation.js): `src/interactive_simulation.js`
- [Saved configurations](https://github.com/khp-informatics/patient-flow-simulator/blob/master/src/interactive_simulation.js): `src/interactive_simulation.js`
- [Results dashboard](https://github.com/khp-informatics/patient-flow-simulator/blob/master/index.html): `index.html`

### Other components

- **Hospital manager**

## Connections

- Hospital manager → Run and configure: sets options
- Run and configure → Ward definitions: edits wards
- Run and configure → Patient scenarios: selects patients
- Run and configure → Run settings: sets run mode
- Run and configure → Simulation loop: starts or pauses
- Simulation loop → Patient generation: requests arrivals
- Patient generation → Patient model: creates patients
- Simulation loop → Ward and queues: admits and transfers
- Simulation loop → Pool and Exit: initializes wards
- Simulation loop → Ward definitions: initializes wards
- Ward and queues → Priority queue: orders queues
- Simulation loop → Simulation history: records runs
- Simulation loop → Wait and score metrics: summarizes patients
- Simulation loop → Performance charts: plots results
- Simulation loop → Transfer network analysis: builds transfer graph
- Simulation history → Results dashboard: shows history
- Performance charts → Results dashboard: renders charts
- Transfer network analysis → Results dashboard: shows network analysis
- Wait and score metrics → Results dashboard: shows performance
- Run and configure → Saved configurations: imports or exports
- Hospital manager → Results dashboard: reviews results