# edouard-rabasse/vrp architecture

> Architecture diagram of the GitHub repository edouard-rabasse/vrp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edouard-rabasse/vrp
- Repository: https://github.com/edouard-rabasse/vrp

## Overview

##### Project type and purpose
- This is a hybrid “solver + ML pipeline + visualization” project.
- The Java subsystem (under MSH/) implements VRP solving heuristics and experiments.

##### File structure
- Top-level directories:
- MSH/ – Java-based VRP solver, configs, experiments, JARs, & data sets.
- config/, configs/, environment.yml, requirements.txt – Hydra/YAML configs for Python.
- src/ – Python ML code: data loaders, models, pipeline, solver_client, visualization.
- bash/, commands/ – helper scripts to run solver, training, plotting.
- Tests cover both solver integration and Python pipeline.

##### README
- Describes two main workflows:
- training: “python train.py <config> …”
- Core objective: predict modification probability + show location via heatmap / mask.

##### Main components & interactions
a. VRP Solver Service (Java/M SH)
- Inputs: VRP instance files (TSPLib, custom coords, config XML)
- Outputs: optimal/modifed routes, arc data
- Interfaces: called by Python via solver_client (subprocess invoking JARs or bash scripts)
b. Data Layer (Python src/data, config/data)
- Reads raw routes & modifications; transforms into images/tensors; provides Dataset
c. ML Training Pipeline (train.py → src/train_functions, trainers/)
- Uses config files (Hydra) to instantiate model, optimizer, data loader
- Models: CNN (resnet, vgg), ViT, MFCN, MultiTaskVisualModel
- Losses: classification & localization (heatmap/mask)
d. Scoring & Solver Client (src/pipeline/solver_client.py)
- Optionally computes solver‐based features or gets ground truth from MSH
e. Optimized Pipeline (src/pipeline/optimized_pipeline.py)
- Orchestrates end-to-end: load model, load data, run inference, post-process heatmaps
- Generates and overlays heatmaps/masks onto route images
- Scripts & notebooks to plot ROC, results, batch heatmaps
g. Configuration Management
- Hydra/YAML configs under config/, configs/benchmark.yaml
- Defines model, data, solver, and plotting parameters
h. Orchestration Scripts
- bash/*.sh and commands/*.bat glue the Java solver and Python pipeline

##### Architectural patterns & design principles
- Separation of concerns: solver vs. ML code vs. visualization
- Config-driven instantiation (Hydra pattern) for easy experiment variation
- Modular ML pipeline: loader → model → scorer → visualizer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Entrypoints
    TrainCLI["train.py"]:::cli
    VizCLI["visualize.py"]:::cli

    %% Configuration
    ConfigStore["Config Store"]:::config

    %% Solver Layer
    subgraph "Java Solver Service"
        direction TB
        Instances["Instance Files (TSPLib, coords)"]:::data
        XMLConfigs["XML Configs"]:::config
        VRPService["VRP Solver Service"]:::solver
        Results["Route Data"]:::data
    end

    %% Python Pipeline
    subgraph "Python ML Pipeline"
        direction TB
        DataLoader["Data Loader"]:::data
        MLModel["ML Model (CNN/ViT/MFCN)"]:::ml
        SolverClient["Solver Client & Scoring"]:::pipeline
        OptimPipeline["Optimized Pipeline"]:::pipeline
        Visualizer["Visualizer / Heatmap Generator"]:::viz
    end

    %% Flows
    TrainCLI -->|"uses configs"| ConfigStore
    VizCLI -->|"uses configs"| ConfigStore

    ConfigStore -->|"Hydra/YAML"| XMLConfigs
    ConfigStore -->|"Hydra/YAML"| DataLoader
    ConfigStore -->|"Hydra/YAML"| MLModel
    ConfigStore -->|"Hydra/YAML"| SolverClient

    Instances -->|"instance .txt/.tsp"| VRPService
    XMLConfigs -->|".xml config"| VRPService
    VRPService -->|"route output"| Results

    Results -->|"raw routes"| DataLoader
    DataLoader -->|"tensor batch"| MLModel
    MLModel -->|"predictions"| OptimPipeline
    SolverClient -->|"solver features"| OptimPipeline
    OptimPipeline -->|"heatmap data"| Visualizer

    TrainCLI -->|"start training"| OptimPipeline
    VizCLI -->|"start viz"| Visualizer

    %% Click Events
    click TrainCLI "https://github.com/edouard-rabasse/vrp/blob/main/train.py"
    click VizCLI "https://github.com/edouard-rabasse/vrp/blob/main/visualize.py"
    click ConfigStore "https://github.com/edouard-rabasse/vrp/tree/main/config"
    click XMLConfigs "https://github.com/edouard-rabasse/vrp/tree/main/MSH/MSH/config/"
    click VRPService "https://github.com/edouard-rabasse/vrp/tree/main/MSH/MSH/src"
    click DataLoader "https://github.com/edouard-rabasse/vrp/tree/main/src/data"
    click MLModel "https://github.com/edouard-rabasse/vrp/tree/main/src/models"
    click SolverClient "https://github.com/edouard-rabasse/vrp/blob/main/src/pipeline/solver_client.py"
    click OptimPipeline "https://github.com/edouard-rabasse/vrp/blob/main/src/pipeline/optimized_pipeline.py"
    click Visualizer "https://github.com/edouard-rabasse/vrp/tree/main/src/visualization"

    %% Styles
    classDef cli fill:#ff9f9f,stroke:#333,stroke-width:1px
    classDef config fill:#9be7ff,stroke:#333,stroke-width:1px
    classDef solver fill:#82cfff,stroke:#333,stroke-width:1px
    classDef data fill:#a8ff8a,stroke:#333,stroke-width:1px
    classDef ml fill:#ffb347,stroke:#333,stroke-width:1px
    classDef pipeline fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef viz fill:#cda4de,stroke:#333,stroke-width:1px
```
