# dimastoyanov/ambulance-dispatching architecture

> Architecture diagram of the GitHub repository dimastoyanov/ambulance-dispatching, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dimastoyanov/ambulance-dispatching
- Repository: https://github.com/dimastoyanov/ambulance-dispatching

## Overview

##### Project type and purpose
- This is an academic research pipeline for “Ambulance Dispatching.”
- It couples game-theoretic models with discrete-event simulation to explore ambulance dispatch policies and regulation effects.
- The Jupyter notebooks at the root provide interactive exploration and presentation of results; the src directory contains all the implementation modules.

##### File structure
- Top-level folders and files
– Jupyter notebooks (GT.ipynb, Dispatcher Agent.ipynb, Healthcare Regulation.ipynb): user interface and result walkthrough.
– docs/: static documentation in docx and PDF formats.
– src/: source code subdivided into data, game theory models (gt), Nash equilibrium engine (neng), simulation modules, and shared utilities.
- src/data: raw and aggregated CSV inputs for hospitalizations and transportation networks.
- src/gt: core game-theoretic model definitions plus plotting subpackages.
- src/neng: numerical engine for computing Nash equilibria and strategy profiles.
- src/simulation: discrete-event simulation of patients, hospitals, and transport, plus statistics and plotting.
- Configuration/build scripts: none (pure Python modules).

##### README insights
- Literature references define the academic context.
- Implementation section points to three main notebooks and the /src folder as the implementation.

##### Main components
a. Data layer
– Raw CSV source files under src/data
– Aggregated transportation data
b. Preprocessing/Utilities
– src/common.py for shared routines
– src/data/transportation/prepare_data.py
c. Game Theory Engine
– src/gt/core: models of hospitals, dispatcher, Nash equilibrium routines
– src/neng: solver algorithms
d. Simulation Engine
– src/simulation/core: event and patient flow modeling
– src/simulation/surgery, /transportation: domain-specific extensions
– src/simulation/stats: data collection from runs
e. Visualization/Reporting
– src/gt/plot and src/simulation/plot: generate charts
– Jupyter notebooks: orchestrate modules, render plots, present results
f. External references
– PDF literature, static docs in docs/

##### Relationships and interactions
- Data flows from the Data layer into both the Game Theory Engine and the Simulation Engine.
- The Game Theory Engine may feed optimal dispatch strategies into the Simulation Engine to compare outcomes.
- The Nash equilibrium solver (neng) is invoked by gt/core modules.
- Both engines output results consumed by their respective plotting modules.
- Jupyter notebooks import common, engine modules, run experiments, and render visualizations in-line.

##### Architectural patterns and principles
- Modular separation of concerns: data ingestion, core computation (game vs. simulation), numerical solvers, visualization.
- Pipeline pattern: raw data → preprocessing → modeling → analysis → reporting.
- Reusable library modules (common, neng) that can be tested independently.

##### Detailed capture of essential elements
- Shared/common utilities as a side-connected component.
- Documentation (docs/) as a passive artifact.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataStore(("CSV Data Store")):::data
        RawCSV["Hospitalization CSV"]:::data
        AggrData["Aggregated Transportation Data"]:::data
        DataStore --> RawCSV
        DataStore --> AggrData
    end

    %% Preprocessing / Utilities
    subgraph "Preprocessing / Utilities"
        direction TB
        Common["Common Utilities"]:::util
        PrepTrans["Transport Data Prep"]:::util
    end

    %% Game Theory Engine
    subgraph "Game Theory Engine"
        direction TB
        GtCore["Core Models"]:::compute
        NashIface["Nash Equilibrium Interface"]:::compute
    end

    %% Nash Equilibrium Solver
    subgraph "Nash Equilibrium Solver Engine"
        direction TB
        Solver["Solver Engine"]:::compute
    end

    %% Simulation Engine
    subgraph "Simulation Engine"
        direction TB
        SimCore["Core Event & Patient Modeling"]:::compute
        SurgeryMod["Surgery Module"]:::compute
        TransMod["Transportation Module"]:::compute
        Stats["Statistics Collection"]:::compute
    end

    %% Visualization / Reporting
    subgraph "Visualization / Reporting"
        direction TB
        GtPlot["Game Theory Plotting"]:::viz
        SimPlot["Simulation Plotting"]:::viz
    end

    %% Notebook Interface
    subgraph "Notebook Interface"
        direction TB
        NB1["GT.ipynb"]:::notebook
        NB2["Dispatcher Agent.ipynb"]:::notebook
        NB3["Healthcare Regulation.ipynb"]:::notebook
    end

    %% Documentation
    Docs["Static Documentation"]:::docs

    %% Connections: Data to Preprocessor
    RawCSV -->|"hospital CSV"| PrepTrans
    AggrData -->|"transport data"| PrepTrans

    %% Data to Engines
    RawCSV -->|"hospital CSV"| GtCore
    AggrData -->|"transportation data"| GtCore
    RawCSV -->|"hospital CSV"| SimCore
    AggrData -->|"transportation data"| SimCore

    %% Utilities to Engines
    Common -->|"shared routines"| GtCore
    Common -->|"shared routines"| SimCore

    %% Game Theory flow
    GtCore -->|"defines Nash routines"| NashIface
    NashIface -->|"invoke solver"| Solver

    %% Strategies to Simulation
    GtCore -->|"strategy profiles"| SimCore

    %% Engines to Plotting
    GtCore -->|"model results"| GtPlot
    Stats -->|"simulation results"| SimPlot
    SimPlot -->|"plots"| NB1
    SimPlot -->|"plots"| NB2
    SimPlot -->|"plots"| NB3
    GtPlot -->|"plots"| NB1
    GtPlot -->|"plots"| NB2
    GtPlot -->|"plots"| NB3

    %% Docs
    Docs

    %% Click Events
    click DataStore "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/src/data"
    click RawCSV "https://github.com/dimastoyanov/ambulance-dispatching/blob/master/src/data/hospitalization.csv"
    click AggrData "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/src/data/transportation/aggr"
    click Common "https://github.com/dimastoyanov/ambulance-dispatching/blob/master/src/common.py"
    click PrepTrans "https://github.com/dimastoyanov/ambulance-dispatching/blob/master/src/simulation/transportation/prepare_data.py"
    click GtCore "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/src/gt/core"
    click NashIface "https://github.com/dimastoyanov/ambulance-dispatching/blob/master/src/gt/core/NashEquilibrium.py"
    click Solver "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/src/neng"
    click SimCore "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/src/simulation/core"
    click SurgeryMod "https://github.com/dimastoyanov/ambulance-dispatching/blob/master/src/simulation/surgery/SurgeryData.py"
    click TransMod "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/src/simulation/transportation"
    click Stats "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/src/simulation/stats"
    click GtPlot "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/src/gt/plot"
    click SimPlot "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/src/simulation/plot"
    click NB1 "https://github.com/dimastoyanov/ambulance-dispatching/blob/master/GT.ipynb"
    click NB2 "https://github.com/dimastoyanov/ambulance-dispatching/blob/master/Dispatcher Agent.ipynb"
    click NB3 "https://github.com/dimastoyanov/ambulance-dispatching/blob/master/Healthcare Regulation.ipynb"
    click Docs "https://github.com/dimastoyanov/ambulance-dispatching/tree/master/docs/"

    %% Styles
    classDef data fill:#b2f2bb,stroke:#2f855a,color:#1a202c
    classDef compute fill:#bee3f8,stroke:#2b6cb0,color:#1a202c
    classDef util fill:#fefcbf,stroke:#d69e2e,color:#1a202c
    classDef viz fill:#fed7d7,stroke:#c05621,color:#1a202c
    classDef notebook fill:#e9d8fd,stroke:#6b46c1,color:#1a202c
    classDef docs fill:#edf2f7,stroke:#718096,color:#1a202c
```
