# naroaipar/vrp-frop architecture

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

- Interactive diagram: https://gitdiagram.com/naroaipar/vrp-frop
- Repository: https://github.com/naroaipar/vrp-frop

## Overview

##### Project Type and Purpose
- This is an academic/industrial-style ML system implementing a Reinforcement Learning solution for the Stochastic Vehicle Routing Problem (SVRP).
- The goal is to train a neural‐policy with attention and memory embeddings to solve routing under demand and travel‐cost uncertainty.

##### File‐Structure Analysis
- Top-Level:
- main.py – Orchestrator for training and testing
- config.py – Global hyperparameters and CLI flags
- checkpoints/ – Serialized model states per epoch
- results/ – Generated CSVs and figures
- models/ – Policy network (embeddings, attention, output)
- env/ – Custom SVRP environment (state generation, weather simulation)
- training/ – RL algorithms (REINFORCE, baseline) and training utilities
- inference/ – Deployment strategies (greedy, random sampling, beam search)
- Build/Deployment Files: requirements.txt, venv/
- Data Resources: env/*.txt (demands, positions, weather), results/

##### Key README Insights
- Architecture components are already separated by folder: environment, model, training, inference.
- Core algorithm: policy gradient (REINFORCE) with learnable baseline and attention mechanism.
- Multiple inference modes for evaluation.

##### Final Advice
- Both control flow (orchestration) and data flow (state/action/reward, checkpoint I/O, result plots).
- Keep it high-level enough to avoid overwhelming detail, but detailed enough to illustrate every folder/module’s role and interaction.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    subgraph "Orchestration" 
        direction TB
        config["Configuration Module\n(config.py)"]:::orchestration
        main["CLI / Driver\n(main.py)"]:::orchestration
    end

    %% Environment Layer
    subgraph "Environment" 
        direction TB
        env_core["SVRP Environment\n(env/svrp_env.py)"]:::compute
        weather["Weather Simulator\n(env/weather.py)"]:::compute
    end

    %% Model Layer
    subgraph "Policy Model"
        direction TB
        embedding["Embedding Layers\n(models/embedding.py)"]:::compute
        attention["Attention Mechanism\n(models/attention.py)"]:::compute
        policy_net["Action Decoder & Policy Interface\n(models/policy.py)"]:::compute
    end

    %% Training Layer
    subgraph "Training Engine"
        direction TB
        reinforce["REINFORCE Algorithm\n(training/reinforce.py)"]:::compute
        baseline["Baseline Model Trainer\n(training/baseline.py)"]:::compute
        metrics["Metrics & Visualization Generator\n(training/training_metrics_graph_generator.py)"]:::compute
    end

    %% Inference Layer
    subgraph "Inference Module"
        direction TB
        inference["Inference Strategies\n(inference/inference.py)"]:::orchestration
    end

    %% Data & Storage Layer
    subgraph "Data & Artifacts"
        direction TB
        subgraph "Environment Data Files"
            direction TB
            demands20["demands20.txt"]:::data
            demands50["demands50.txt"]:::data
            positions20["positions20.txt"]:::data
            positions50["positions50.txt"]:::data
        end
        checkpoints["Checkpoints\n(checkpoints/)"]:::storage
        results_csv["Results CSV\n(results/results.csv)"]:::storage
        figs["Figures\n(results/figs)"]:::storage
    end

    %% Utilities & Build
    subgraph "Utilities & Build"
        direction TB
        clear_dirs["Directory Cleanup\n(clear_directories.py)"]:::orchestration
        run_combos["Experiment Runner\n(run_combinations.py)"]:::orchestration
        requirements["Dependencies\n(requirements.txt)"]:::build
        venv["Virtual Env\n(venv/)"]:::build
    end

    %% Connections: Orchestration to modules
    config -->|"load config"| main
    main -->|"instantiate"| env_core
    main -->|"instantiate"| embedding

    %% Environment ↔ Model loop
    env_core -->|"state"| embedding
    embedding -->|"embedded state"| attention
    attention -->|"context"| policy_net
    policy_net -->|"action"| env_core
    weather -->|"weather data"| env_core

    %% Training interactions
    embedding -->|"forward pass"| reinforce
    attention -->|"forward pass"| reinforce
    policy_net -->|"policy eval"| reinforce
    env_core -->|"reward & next state"| reinforce
    reinforce -->|"update params"| embedding
    reinforce -->|"update params"| attention
    reinforce -->|"update params"| policy_net
    reinforce -->|"log metrics"| metrics
    metrics -->|"generate plots"| figs
    reinforce -->|"save checkpoint"| checkpoints
    baseline -->|"baseline update"| reinforce

    %% Inference Path
    main -->|"select strategy"| inference
    inference -->|"load checkpoint"| checkpoints
    inference -->|"state"| embedding
    inference -->|"action"| env_core
    inference -->|"log results"| results_csv

    %% Utilities & Build references
    run_combos --> main
    clear_dirs --> checkpoints
    clear_dirs --> figs
    requirements -.->|"install deps"| venv

    %% Click Events
    click config "https://github.com/naroaipar/vrp-frop/blob/main/config.py"
    click main "https://github.com/naroaipar/vrp-frop/blob/main/main.py"
    click env_core "https://github.com/naroaipar/vrp-frop/blob/main/env/svrp_env.py"
    click weather "https://github.com/naroaipar/vrp-frop/blob/main/env/weather.py"
    click demands20 "https://github.com/naroaipar/vrp-frop/blob/main/env/demands20.txt"
    click demands50 "https://github.com/naroaipar/vrp-frop/blob/main/env/demands50.txt"
    click positions20 "https://github.com/naroaipar/vrp-frop/blob/main/env/positions20.txt"
    click positions50 "https://github.com/naroaipar/vrp-frop/blob/main/env/positions50.txt"
    click embedding "https://github.com/naroaipar/vrp-frop/blob/main/models/embedding.py"
    click attention "https://github.com/naroaipar/vrp-frop/blob/main/models/attention.py"
    click policy_net "https://github.com/naroaipar/vrp-frop/blob/main/models/policy.py"
    click reinforce "https://github.com/naroaipar/vrp-frop/blob/main/training/reinforce.py"
    click baseline "https://github.com/naroaipar/vrp-frop/blob/main/training/baseline.py"
    click metrics "https://github.com/naroaipar/vrp-frop/blob/main/training/training_metrics_graph_generator.py"
    click checkpoints "https://github.com/naroaipar/vrp-frop/tree/main/checkpoints/"
    click inference "https://github.com/naroaipar/vrp-frop/blob/main/inference/inference.py"
    click results_csv "https://github.com/naroaipar/vrp-frop/blob/main/results/results.csv"
    click figs "https://github.com/naroaipar/vrp-frop/tree/main/results/figs"
    click clear_dirs "https://github.com/naroaipar/vrp-frop/blob/main/clear_directories.py"
    click run_combos "https://github.com/naroaipar/vrp-frop/blob/main/run_combinations.py"
    click requirements "https://github.com/naroaipar/vrp-frop/blob/main/requirements.txt"
    click venv "https://github.com/naroaipar/vrp-frop/tree/main/venv/"

    %% Styles
    classDef orchestration fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef compute fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef storage fill:#87CEEB,stroke:#333,stroke-width:1px;
    classDef build fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
