# mibha/project-hero architecture

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

- Interactive diagram: https://gitdiagram.com/mibha/project-hero
- Repository: https://github.com/mibha/project-hero

## Overview

##### Project type and purpose
- Project HERO is a standalone AI-powered optimization system built in Python. It integrates a high-fidelity traffic simulator (SUMO) with real-world map data (OpenStreetMap) to train Multi-Agent Reinforcement Learning (MARL) agents. Its purpose is to minimize emergency response times via cooperative dispatch.

##### File structure
- Top-level directories:
- data/              – contains historical incident prediction datasets
- notebooks/         – exploratory Jupyter notebooks for analysis and prototyping
- simulation_files/  – SUMO network maps, route files, and configuration XMLs
- src/               – core Python modules implementing environment wrappers, agent code, training loops, and utility functions
- Configuration/build files:
- requirements.txt   – Python dependencies
- .gitignore
- README.md

##### README insights
- Core architecture:
- Simulation engine (SUMO) ↔ Python via TraCI
- MARL training using Ray RLlib
- Data preprocessing and predictive hotspot modeling with Pandas/Scikit-learn

##### Detail
- Blocks with key technologies (e.g., “Ray RLlib”, “TraCI API”)
- Both offline (training) and online (inference/dispatch) flows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Documentation
    Docs["Project Documentation"]:::docs
    Gitignore["Git Ignore Configuration"]:::docs

    %% Data Sources
    HistData["Historical Incident Logs\n(data/)"]:::data
    MapData["Map Data (OSM)\n(simulation_files/)"]:::data

    %% Data Preprocessing
    Preprocessor["Data Ingestion &\nPreprocessing"]:::data

    %% Simulation Components
    SUMO["SUMO Traffic Simulator"]:::sim
    TraCI["TraCI API Bridge"]:::sim

    %% Environment Layer
    EnvWrapper["MARL Environment Wrapper\n(Adapter Pattern)"]:::sim
    Hotspot["Predictive Hotspot Module\n(Scikit-learn)"]:::data

    %% Training Components
    RLTrainer["Ray RLlib Trainer\n(Distributed MARL)"]:::ml
    PolicyServer["Policy Server / Learner"]:::ml

    %% Dispatch Components
    Dispatcher["Runtime Dispatcher\n(Real-time Dispatch)"]:::dispatch

    %% Monitoring & Notebooks
    Monitoring["Monitoring & Logging"]:::mon
    Notebook["Jupyter Notebooks\n(Analysis/Visualization)"]:::mon

    %% Offline Documentation Links
    Docs --> HistData
    Docs --> MapData
    click Docs "https://github.com/mibha/project-hero/blob/main/README.md"
    click Gitignore "https://github.com/mibha/project-hero/blob/main/.gitignore"

    %% Data Flow
    HistData -->|raw logs| Preprocessor
    MapData -->|network files| Preprocessor
    Preprocessor -->|processed data| EnvWrapper

    %% Simulation Loop
    EnvWrapper -->|state & observations| RLTrainer
    RLTrainer -->|actions| EnvWrapper
    EnvWrapper -->|TraCI calls| TraCI
    TraCI -->|simulation control| SUMO
    SUMO -->|vehicle states| TraCI

    %% Hotspot Integration
    Preprocessor -->|training data| Hotspot
    Hotspot -->|predictions| EnvWrapper

    %% Training to Policy Server
    RLTrainer -->|trained policies| PolicyServer

    %% Deployment Loop
    PolicyServer -->|policies| Dispatcher
    Dispatcher -->|dispatch decisions| SUMO

    %% Monitoring & Notebooks (optional)
    Notebook -.-> Preprocessor
    Notebook -.-> Hotspot
    RLTrainer --> Monitoring
    Dispatcher --> Monitoring

    %% Styles
    classDef data fill:#E3F2FD,stroke:#2196F3,stroke-width:2px
    classDef sim fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px
    classDef ml fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef dispatch fill:#F3E5F5,stroke:#9C27B0,stroke-width:2px
    classDef mon fill:#ECEFF1,stroke:#607D8B,stroke-width:2px,stroke-dasharray: 5 5
    classDef docs fill:#FFFDE7,stroke:#FBC02D,stroke-width:2px

    class Docs,Gitignore docs
    class HistData,MapData,Preprocessor,Hotspot data
    class SUMO,TraCI,EnvWrapper sim
    class RLTrainer,PolicyServer ml
    class Dispatcher dispatch
    class Monitoring,Notebook mon
```
