# profreusch2026mor/sustainable_freight_mode_choice architecture

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

- Interactive diagram: https://gitdiagram.com/profreusch2026mor/sustainable_freight_mode_choice
- Repository: https://github.com/profreusch2026mor/sustainable_freight_mode_choice

## Overview

1. **Repository purpose**
   This is a research/analysis repository for a multimodal freight mode-choice problem, not a production service. The core architecture is a pipeline for loading transport-network instances, solving an optimization model, comparing it with heuristics, and exporting experiment results for a thesis-style writeup.

2. **Main domain boundary: `freight_routing/`**
   This package is the central application layer. It likely contains the reusable domain objects and logic shared across solver runs, heuristics, notebooks, and experiments:
   - `data_models.py` for the network, shipment, terminal, and transport entities
   - `data_loader.py` for turning JSON instance files into those domain objects
   - `model.py` for the exact optimization model
   - `visualization.py` for plotting or inspecting solutions

3. **Input data layer: `dataset/`**
   The network instances live as JSON files: `small_network.json`, `medium_network.json`, `large_network.json`, and `test_network.json`. This is the primary input boundary into the system. `data_collector.py` suggests a preprocessing or instance-building step that feeds these JSON datasets.

4. **Exact optimization path**
   The README describes a MILP-based decision model. In the codebase, this is most likely implemented in `freight_routing/model.py` and solved using Python optimization libraries mentioned in the README, specifically **PuLP** and **OR-Tools**. This layer takes the loaded instance data and produces route/mode decisions under constraints such as deadlines, capacities, and terminal transfers.

5. **Heuristic path**
   The `heuristics/` directory contains alternative solution approaches:
   - `dijkstra_router.py` for shortest-path style routing
   - `Tabu search Heuristik.py` for a metaheuristic search
   These are separate from the exact model and likely operate on the same domain data but with a faster, approximate decision process.

6. **Experimentation and benchmarking**
   `experiments/` is the evaluation subsystem. `run_experiments.py` appears to orchestrate solver runs, sensitivity analyses, or scenario sweeps. `compare_solver_heuristic.py` explicitly compares exact and heuristic approaches. The `results/` folder stores generated CSV/MD outputs, making experiments reproducible and separable from core model code.

7. **Data flow across the system**
   The main flow is: dataset JSON files → `data_loader`/`data_models` → exact model or heuristic solvers → experiment scripts → result tables/plots. This is the key architecture boundary to capture in a diagram: instance data is transformed into a domain representation, then consumed by two different solution strategies.

8. **Analysis and presentation layer**
   The `notebooks/` directory contains exploratory and validation notebooks such as `dijkstra_vs_solver.ipynb`, `multimodal_routing.ipynb`, and `scaling_tests.ipynb`. These are not part of the core runtime; they sit on top of the solver/data layers for analysis, debugging, and presentation of findings.

9. **Documentation and thesis output**
   `documentation/` is a Typst-based document tree, with chapters like introduction, implementation, results, and conclusion. This suggests the repository doubles as the project’s thesis/report source. The `presentations/` folder also uses Typst for slides or pitch material.

10. **Validation and CI**
    The project has GitHub Actions CI (`.github/workflows/ci.yml`) and at least one test file (`tests/test_run_experiments.py`). The test boundary appears focused on validating experiment execution rather than a broad unit-test suite. This is important because it indicates the repository’s quality gate is centered on reproducible computations.

11. **Supporting metadata and tooling**
    `pyproject.toml` and `requirements.txt` define the Python environment. `README.md` and `literature/` support the research workflow, with `sources.bib` and a literature summary feeding the documentation. These are supporting assets rather than runtime components.

12. **How to draw the architecture**
    A correct diagram should show four major blocks:
    - **Instance/data preparation** (`dataset/`, `data_collector.py`)
    - **Core freight-routing model** (`freight_routing/`)
    - **Alternative heuristics and benchmarking** (`heuristics/`, `experiments/`)
    - **Research outputs** (`results/`, `notebooks/`, `documentation/`, `presentations/`)
    
    The most important dependency arrows go from the dataset into the core package, then outward into solver/heuristic experiment pipelines, and finally into stored results and documentation.

Main entry points: [`experiments/run_experiments.py`](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/experiments/run_experiments.py) (Run experiments), [`freight_routing/model.py`](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/model.py) (MILP model), [`freight_routing/data_models.py`](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/data_models.py) (Domain models), [`experiments/results`](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/experiments/results) (Results tables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_inputs["Instance prep"]
  node_node_dataset_json[("Network data<br/>JSON instances")]
  node_node_data_collector["Collector<br/>preprocessing<br/>[data_collector.py]"]
end

subgraph group_group_core["Core model"]
  node_node_data_models["Domain models<br/>entities<br/>[data_models.py]"]
  node_node_data_loader["Loader<br/>instance parser<br/>[data_loader.py]"]
  node_node_model["MILP model<br/>exact optimizer<br/>[model.py]"]
  node_node_visualization["Plots<br/>solution viz<br/>[visualization.py]"]
end

subgraph group_group_alt["Alternatives"]
  node_node_dijkstra["Dijkstra router<br/>heuristic routing<br/>[dijkstra_router.py]"]
  node_node_tabu["Tabu search<br/>metaheuristic"]
  node_node_run_experiments["Run experiments<br/>experiment orchestrator<br/>[run_experiments.py]"]
  node_node_compare["Compare methods<br/>benchmarking"]
end

subgraph group_group_outputs["Research outputs"]
  node_node_results_csv[("Results tables<br/>experiment outputs")]
  node_node_notebooks["Notebooks"]
  node_node_docs["Documentation<br/>Typst thesis"]
  node_node_presentations["Slides<br/>Typst presentation"]
end

subgraph group_group_tooling["Project tooling"]
  node_node_readme["README<br/>project overview<br/>[README.md]"]
  node_node_ci["CI workflow<br/>GitHub Actions<br/>[ci.yml]"]
  node_node_tests["Tests<br/>validation"]
  node_node_env["Python env<br/>dependencies<br/>[pyproject.toml]"]
end

node_node_dataset_json -->|"raw instances"| node_node_data_collector
node_node_dataset_json -->|"loads"| node_node_data_loader
node_node_data_collector -->|"feeds"| node_node_data_loader
node_node_data_loader -->|"builds"| node_node_data_models
node_node_data_models -->|"input state"| node_node_model
node_node_data_models -->|"input state"| node_node_dijkstra
node_node_data_models -->|"input state"| node_node_tabu
node_node_model -->|"solution"| node_node_visualization
node_node_dijkstra -->|"baseline"| node_node_run_experiments
node_node_tabu -->|"baseline"| node_node_run_experiments
node_node_model -->|"exact runs"| node_node_run_experiments
node_node_run_experiments -->|"compare"| node_node_compare
node_node_compare -->|"writes"| node_node_results_csv
node_node_run_experiments -->|"writes"| node_node_results_csv
node_node_results_csv -->|"analyzed in"| node_node_notebooks
node_node_results_csv -->|"reported in"| node_node_docs
node_node_readme -.->|"describes"| node_node_model
node_node_env -.->|"supports"| node_node_model
node_node_env -.->|"supports"| node_node_run_experiments
node_node_ci -->|"runs"| node_node_tests
node_node_tests -->|"checks"| node_node_run_experiments
node_node_presentations -->|"extends"| node_node_docs

click node_node_dataset_json "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/dataset"
click node_node_data_collector "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/dataset/data_collector.py"
click node_node_data_models "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/data_models.py"
click node_node_data_loader "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/data_loader.py"
click node_node_model "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/model.py"
click node_node_visualization "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/visualization.py"
click node_node_dijkstra "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/heuristics/dijkstra_router.py"
click node_node_tabu "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/heuristics/Tabu search Heuristik.py"
click node_node_run_experiments "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/experiments/run_experiments.py"
click node_node_compare "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/experiments/compare_solver_heuristic.py"
click node_node_results_csv "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/experiments/results"
click node_node_notebooks "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/notebooks"
click node_node_docs "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/documentation"
click node_node_presentations "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/presentations"
click node_node_readme "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/README.md"
click node_node_ci "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/.github/workflows/ci.yml"
click node_node_tests "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/tests/test_run_experiments.py"
click node_node_env "https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_dataset_json,node_node_data_collector toneBlue
class node_node_data_models,node_node_data_loader,node_node_model,node_node_visualization toneAmber
class node_node_dijkstra,node_node_tabu,node_node_run_experiments,node_node_compare toneMint
class node_node_results_csv,node_node_notebooks,node_node_docs,node_node_presentations toneRose
class node_node_readme,node_node_ci,node_node_tests,node_node_env toneIndigo
```

## Components

### Instance prep

Transport-network instances and preprocessing into domain objects.

- [Network data](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/dataset): JSON instances · Prepared freight-network datasets used as the main input boundary. · `dataset`
- [Collector](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/dataset/data_collector.py): preprocessing · Builds or preprocesses instance data for the dataset boundary. · `dataset/data_collector.py`

### Core model

Shared freight-routing domain types, loader, exact optimization model, and solution visualization.

- [Domain models](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/data_models.py): entities · Network, shipment, terminal, and transport objects shared across the repository. · `freight_routing/data_models.py`
- [Loader](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/data_loader.py): instance parser · Turns JSON instances into freight-routing domain objects. · `freight_routing/data_loader.py`
- [MILP model](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/model.py): exact optimizer · Defines the exact multimodal freight mode-choice optimization model. · `freight_routing/model.py`
- [Plots](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/freight_routing/visualization.py): solution viz · Visualizes or inspects routing and optimization outputs. · `freight_routing/visualization.py`

### Alternatives

Heuristic solvers and experiment orchestration for benchmarking.

- [Dijkstra router](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/heuristics/dijkstra_router.py): heuristic routing · Shortest-path style routing approach used as a heuristic baseline. · `heuristics/dijkstra_router.py`
- [Tabu search](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/HEAD/heuristics/Tabu%20search%20Heuristik.py): metaheuristic · Tabu-search heuristic for approximate route and mode selection. · `heuristics/Tabu search Heuristik.py`
- [Run experiments](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/experiments/run_experiments.py): experiment orchestrator · Coordinates solver runs, scenario sweeps, and sensitivity analyses. · `experiments/run_experiments.py`
- [Compare methods](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/experiments/compare_solver_heuristic.py): benchmarking · Compares exact optimization results against heuristic solutions. · `experiments/compare_solver_heuristic.py`

### Research outputs

Results, notebooks, documentation, and presentation artifacts for analysis and thesis writing.

- [Results tables](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/experiments/results): experiment outputs · Stored CSV and markdown outputs from computational experiments. · `experiments/results`
- [Notebooks](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/notebooks): analysis notebooks · Exploratory notebooks for routing analysis, scaling, and solver comparison. · `notebooks`
- [Documentation](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/documentation): Typst thesis · Thesis/report source with chapters, appendix, and supporting templates. · `documentation`
- [Slides](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/tree/main/presentations): Typst presentation · Presentation materials for pitches or project updates. · `presentations`

### Project tooling

Repository support files for environment, CI, and validation.

- [README](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/README.md): project overview · Top-level project description and usage guidance. · `README.md`
- [CI workflow](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/.github/workflows/ci.yml): GitHub Actions · Continuous integration workflow for repository validation. · `.github/workflows/ci.yml`
- [Tests](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/tests/test_run_experiments.py): validation · Smoke test coverage focused on experiment execution. · `tests/test_run_experiments.py`
- [Python env](https://github.com/profreusch2026mor/sustainable_freight_mode_choice/blob/main/pyproject.toml): dependencies · Project dependency and packaging definitions. · `pyproject.toml`

## Connections

- Network data → Collector: raw instances · JSON network data is prepared and curated before loading.
- Network data → Loader: loads · Instance files are parsed into runtime objects.
- Collector → Loader: feeds · Preprocessed instance data enters the loader boundary.
- Loader → Domain models: builds · Loader materializes the domain entities used across the repo.
- Domain models → MILP model: input state · Exact optimization operates on the shared freight domain model.
- Domain models → Dijkstra router: input state · Heuristics reuse the same network and shipment representation.
- Domain models → Tabu search: input state · Metaheuristic search consumes the shared domain objects.
- MILP model → Plots: solution · Optimization outputs are rendered or inspected visually.
- Dijkstra router → Run experiments: baseline · Heuristic results are included in experiment runs.
- Tabu search → Run experiments: baseline · Metaheuristic results are included in experiment runs.
- MILP model → Run experiments: exact runs · The MILP model is orchestrated during experiments.
- Run experiments → Compare methods: compare · Experiment outputs feed solver-versus-heuristic comparison.
- Compare methods → Results tables: writes · Benchmarking produces persisted result tables and summaries.
- Run experiments → Results tables: writes · Experiments export CSV and markdown artifacts.
- Results tables → Notebooks: analyzed in · Stored results are explored in notebooks.
- Results tables → Documentation: reported in · Results are summarized in the thesis/documentation tree.
- README → MILP model: describes · Repository overview documents the core modeling workflow.
- Python env → MILP model: supports · Python dependencies enable the optimization implementation.
- Python env → Run experiments: supports · Experiment scripts depend on the project environment.
- CI workflow → Tests: runs · CI validates the experiment-focused test suite.
- Tests → Run experiments: checks · Tests focus on reproducible experiment execution.
- Slides → Documentation: extends · Presentation material complements the written research output.
