# felicze/3l-cvrp architecture

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

- Interactive diagram: https://gitdiagram.com/felicze/3l-cvrp
- Repository: https://github.com/felicze/3l-cvrp

## Overview

1. The core C++ implementation that contains the branch‐and‐cut algorithm and its numerous submodules.

##### Main components
- Core Algorithm (C++ Source)
- This component is implemented in the “cpp/3L-VehicleRouting” directory. It includes several submodules:
- 3L-VehicleRoutingApplication: Entry point/application (contains the main algorithm logic, reading parameters, executing solver, etc.).
- CommonBasics: Contains fundamental helper functions and algorithmic building blocks (e.g., base models, helper functions for CP and MIP services).
- ContainerLoading: Implements the three-dimensional container loading subproblem; includes the exact CP model for checking route feasibility and different packing algorithms.
- VehicleRouting: Handles the vehicle routing aspects (e.g., separation of cuts, branch and cut solvers, heuristics, and modeling of instances and solutions).
- External integration: This part makes use of third-party libraries and code packages that are provided in “external” (e.g., CLI11 for command line parsing, cvrpsep for separation of cuts, nlohmann for JSON).
- Build and configuration: The CMake-based build system (with related CMakeLists.txt files) configures the overall structure and dependency builds.

- Data Management
- Input Data: Under “data/input/3l-cvrp”, this folder holds instance files (JSON format) and parameter files.
- Output Data: Under “data/output/3l-cvrp”, a variety of result variants are stored (e.g., “all-constraints”, “no-fragility”, “no-support”, etc.). These include solution files, logs, statistics, and validator files.

- Visualization and Analysis (Python)
- The “python” folder hosts the visualization application. Key files such as “SolutionVisualizer.py”, “RouteVisualizer.py”, and several analysis modules (like StatisticAnalyzer.py) built using Streamlit support solution and statistic display.
- Configuration files (pyproject.toml and requirements.txt) indicate the dependency management for this component.

##### Relationships and interactions
- The input data (instances and parameters) feed into the C++ algorithm via command-line arguments.
- The branch-and-cut algorithm solves a 3L-CVRP instance, using external libraries (Gurobi for MIP, OR-Tools for CP) in its submodules.
- The algorithm writes its outputs, including detailed solution files and solver logs/statistics to the output directories.
- The Python visualizer reads these outputs (JSON files, logs) and renders interactive solution visualizations and performance statistics.
- External libraries act as supporting services for both the algorithm (e.g., boosting optimization and parsing) and for JSON output management.

##### Important architectural patterns/design principles
- Modularity: Different functional parts of the algorithm (loading, routing, helper routines) are separated into distinct subdirectories (“CommonBasics”, “ContainerLoading”, “VehicleRouting”) clearly mapping to layered responsibilities.
- Separation of concerns: The core solver is isolated from the data operations (inputs/outputs) and from visualization, enabling independent testing and development.
- Use of external libraries to abstract command-line interfaces (CLI11), JSON serialization (nlohmann), and mathematical optimization (Gurobi, OR-Tools) promotes reusability.

##### Relevant technologies and frameworks
- C++ along with CMake as the primary build tool.
- Gurobi (as the MIP solver) and Google OR-Tools (for CP-based loading feasibility).
- Boost and TBB libraries.
- External domain-specific code such as A-MDVRP and CVRPSEP modules.
- For the visualization part: Python, Streamlit, and associated libraries (e.g., requirements.txt dependencies).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Management"
        Input["Input Data (JSON)"]:::data
        Output["Output Data (Results & Logs)"]:::data
    end

    subgraph "Core Solver Engine (C++)"
        A["3L-VehicleRoutingApplication"]:::algo
        B["CommonBasics Module"]:::algo
        C["ContainerLoading Module"]:::algo
        D["VehicleRouting Module"]:::algo
        E["CMake Build Configuration"]:::build
        F["External Integration"]:::external
    end

    subgraph "External Dependencies"
        G["CLI11"]:::external
        H["cvrpsep"]:::external
        I["nlohmann (JSON)"]:::external
        J["Gurobi"]:::external
        K["OR-Tools (CP)"]:::external
        L["Boost & TBB"]:::external
    end

    subgraph "Visualization & Analysis (Python)"
        subgraph "Python Visualization Configuration"
            VizConfig["pyproject.toml"]:::build
            VizReq["requirements.txt"]:::build
        end
        Viz["Python Visualization Application"]:::visual
    end

    %% Data flow
    Input -->|"feeds"| A
    A -->|"calls"| B
    A -->|"calls"| C
    A -->|"calls"| D
    A -->|"configuredBy"| E
    A -->|"uses"| F

    %% External integration dependency
    F -->|"integrates"| G
    F -->|"integrates"| H
    F -->|"integrates"| I
    F -->|"integrates"| J
    F -->|"integrates"| K
    F -->|"integrates"| L

    %% Output flow for visualization
    A -->|"writes"| Output
    Output -->|"readBy"| Viz
    VizConfig -->|"configures"| Viz
    VizReq -->|"configures"| Viz

    %% Styling classes
    class Input,Output data;
    class A,B,C,D algo;
    class E,VizConfig,VizReq build;
    class F,G,H,I,J,K,L external;
    class Viz visual;

    %% Click Events
    click A "https://github.com/felicze/3l-cvrp/blob/main/cpp/3L-VehicleRouting/3L-VehicleRoutingApplication/3L-VehicleRoutingApplication.cpp"
    click B "https://github.com/felicze/3l-cvrp/tree/main/cpp/3L-VehicleRouting/CommonBasics"
    click C "https://github.com/felicze/3l-cvrp/tree/main/cpp/3L-VehicleRouting/ContainerLoading"
    click D "https://github.com/felicze/3l-cvrp/tree/main/cpp/3L-VehicleRouting/VehicleRouting"
    click F "https://github.com/felicze/3l-cvrp/tree/main/cpp/3L-VehicleRouting/external"
    click E "https://github.com/felicze/3l-cvrp/blob/main/cpp/3L-VehicleRouting/CMakeLists.txt"
    click Input "https://github.com/felicze/3l-cvrp/tree/main/data/input/3l-cvrp"
    click Output "https://github.com/felicze/3l-cvrp/tree/main/data/output/3l-cvrp"
    click Viz "https://github.com/felicze/3l-cvrp/tree/main/python/visualization"
    click VizConfig "https://github.com/felicze/3l-cvrp/blob/main/python/pyproject.toml"
    click VizReq "https://github.com/felicze/3l-cvrp/blob/main/python/requirements.txt"
```
