# thought-eater/tabu-search-tasf architecture

> Architecture diagram of the GitHub repository thought-eater/tabu-search-tasf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thought-eater/tabu-search-tasf
- Repository: https://github.com/thought-eater/tabu-search-tasf

## Overview

1. This repo has two main execution surfaces over the same core logic: a CLI entrypoint for long-running simulations/experiments, and a Spring Boot API for CRUD, route queries, simulation state, and solver control. Both sit on top of the same domain model and Tabu Search solver.

2. The architectural center is the logistics network model: airports, flights, shipment requests, route assignments, and complete solutions. Flights are mutable and shared across routes so capacity is tracked in-place; that makes `resetLoads()` and careful state management a required boundary before each solve/replan run.

3. Input data comes from real text files rather than synthetic generation. `AirportsLoader`, `RealFlightLoader`, and `EnviosDataLoader` parse `aeropuertos.txt`, `planes_vuelo.txt`, and the `_envios_*.txt` shipment files into the domain model. `RealNetworkBuilder` assembles these into the directed flight network used by the solver.

4. The solver subsystem is a Tabu Search implementation centered in `TabuSearchSolver` and configured by `TabuSearchConfig`. It builds an initial greedy solution, explores reroute neighborhoods, tracks forbidden moves in a tabu list, and periodically intensifies or diversifies the search. Replanning (`replanify`) is a special shorter run triggered by flight cancellations.

5. The solver’s key constraint is route feasibility against flight capacity and delivery deadlines. Fitness is a penalty-based objective: infeasible routes are worst, late deliveries are next, and delay magnitude is penalized after that. The objective and search behavior are tightly coupled to the mutable flight-load state.

6. Multi-day routing is handled inside the network layer by creating cached virtual next-day flight instances. That matters architecturally because capacity must be preserved across repeated route searches, not just on the original scheduled flights.

7. The CLI program in `Main` drives four simulation modes: E1 period simulation, E2 real-time replanning, E3 collapse simulation, and EXP batch experimentation. These modes differ mainly in time budget, randomness, request scaling, and whether cancellation events are injected, but they all use the same solver and network builder.

8. The API layer is organized by resource/controller boundaries: airports, flights, shipments, routes, simulation, and solver. Controllers return DTOs, not raw domain objects, and `ApiMapper` bridges between persistence/domain models and response/request shapes. `CorsConfig` and `ApiExceptionHandler` provide API cross-cutting behavior.

9. Persistence is database-backed and migration-driven. The `migrations/` directory defines airports, flights, shipments, shipment-flight assignments, and solver control tables, with seed/adjustment migrations layered on top. The `service/db` package contains row/insert models plus `SimulationDbRepository`, which is the database access boundary used by the simulation and solver-control services.

10. `ShipmentImportService`, `SimulationDataService`, `SolverState`, and the `service/solver` package form the application/service layer. This is where imported shipments are turned into solver inputs, simulation status is tracked, and solver control settings are read or updated independently of the raw controllers.

11. Important repository-level boundaries are explicit: DTOs are separated from domain objects, loaders are separated from solver logic, and the persistence schema is separated from the in-memory graph. That separation is what makes the same codebase support both offline batch runs and interactive API-driven operations.

12. Tooling and deployment are lightweight but important: Java 17 + Maven are the primary runtime/build stack, Dockerfiles and `compose.yaml` support containerized execution, and `scripts/init_db.sh` suggests a database bootstrap path for the migration-driven persistence layer.

13. Tests are mostly integration-focused. There are controller/service/solver tests under `src/test`, plus a nonstandard smoke-test runner in `src/main/java/pe/edu/pucp/tasf/test/RunnerTest.java`, which indicates the project is validated by end-to-end execution against the real data files rather than isolated unit tests alone.

14. For an architecture diagram, the key flows are: text-file and DB inputs into loaders/repositories, loaders/builders into the shared logistics network, the network into the Tabu solver, and solver outputs back out to either CLI reports/CSV or API DTO responses. The mutable-flight state and database migration layer are the two most important implementation boundaries to reflect.

Main entry points: [`src/main/java/pe/edu/pucp/tasf/algorithm/TabuSearchSolver.java`](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/algorithm/TabuSearchSolver.java) (Tabu solver), [`src/main/java/pe/edu/pucp/tasf/api/controller/RoutesController.java`](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/api/controller/RoutesController.java) (API controllers), [`src/main/java/pe/edu/pucp/tasf/model/LogisticsNetwork.java`](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/model/LogisticsNetwork.java) (Network model), [`src/main/java/pe/edu/pucp/tasf/service/solver/TabuSolverOrchestratorService.java`](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/solver/TabuSolverOrchestratorService.java) (Solver orch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI"]
  node_node_main["Main<br/>CLI modes<br/>[Main.java]"]
end

subgraph group_group_api["API"]
  node_node_api_ctrl["API controllers<br/>HTTP resources"]
  node_node_api_dto["DTO layer<br/>request/response"]
end

subgraph group_group_core["Core model"]
  node_node_model_network{{"Network model<br/>domain graph"}}
  node_node_flight["Flight state<br/>mutable capacity<br/>[Flight.java]"]
  node_node_solution["Route solution<br/>assignment model<br/>[Solution.java]"]
  node_node_tabu{{"Tabu solver<br/>search engine"}}
  node_node_config["Solver config<br/>search config"]
end

subgraph group_group_data["Inputs"]
  node_node_builder["Network builder<br/>network assembly"]
  node_node_loaders["Text loaders<br/>file parsers"]
end

subgraph group_group_persist["Persistence"]
  node_node_dbrepo[("DB repo<br/>data access")]
  node_node_migrations["Migrations<br/>schema DDL"]
end

subgraph group_group_service["Services"]
  node_node_mapper["API mapper<br/>translation<br/>[ApiMapper.java]"]
  node_node_simsvc["Simulation svc<br/>application service"]
  node_node_import["Import service<br/>ingestion service"]
  node_node_solver_orch["Solver orch<br/>orchestration"]
  node_node_solver_state(("Solver state<br/>control state<br/>[SolverState.java]"))
end

subgraph group_group_ops["Ops"]
  node_node_ops["Runtime ops<br/>docker+bootstrap"]
  node_node_tests["Tests"]
end

node_node_main -->|"builds network"| node_node_builder
node_node_main -->|"runs solver"| node_node_tabu
node_node_loaders -->|"parsed by"| node_node_builder
node_node_builder -->|"creates"| node_node_model_network
node_node_model_network -->|"contains"| node_node_flight
node_node_model_network -->|"yields"| node_node_solution
node_node_tabu -->|"configured by"| node_node_config
node_node_tabu -->|"searches"| node_node_model_network
node_node_tabu -->|"produces"| node_node_solution
node_node_tabu -->|"updates capacity"| node_node_flight
node_node_api_ctrl -->|"returns"| node_node_api_dto
node_node_api_ctrl -->|"uses"| node_node_mapper
node_node_api_ctrl -->|"coordinates"| node_node_solver_orch
node_node_api_ctrl -->|"queries"| node_node_simsvc
node_node_mapper -->|"maps domain"| node_node_model_network
node_node_simsvc -->|"imports"| node_node_import
node_node_simsvc -->|"tracks"| node_node_solver_state
node_node_solver_orch -->|"executes"| node_node_tabu
node_node_solver_orch -->|"reads/writes"| node_node_dbrepo
node_node_dbrepo -->|"backed by"| node_node_migrations
node_node_ops -.->|"boots db"| node_node_migrations
node_node_tests -.->|"covers"| node_node_api_ctrl
node_node_tests -.->|"covers"| node_node_solver_orch
node_node_tests -.->|"covers"| node_node_main

click node_node_main "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/Main.java"
click node_node_builder "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/util/RealNetworkBuilder.java"
click node_node_loaders "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/io/RealFlightLoader.java"
click node_node_model_network "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/model/LogisticsNetwork.java"
click node_node_flight "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/model/Flight.java"
click node_node_solution "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/model/Solution.java"
click node_node_tabu "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/algorithm/TabuSearchSolver.java"
click node_node_config "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/algorithm/TabuSearchConfig.java"
click node_node_api_ctrl "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/api/controller/RoutesController.java"
click node_node_api_dto "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/api/dto/RoutesSolveResponse.java"
click node_node_mapper "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/ApiMapper.java"
click node_node_simsvc "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/SimulationDataService.java"
click node_node_import "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/ShipmentImportService.java"
click node_node_solver_orch "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/solver/TabuSolverOrchestratorService.java"
click node_node_solver_state "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/SolverState.java"
click node_node_dbrepo "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/db/SimulationDbRepository.java"
click node_node_migrations "https://github.com/thought-eater/tabu-search-tasf/blob/main/migrations/0001_create_airports_table.up.sql"
click node_node_ops "https://github.com/thought-eater/tabu-search-tasf/tree/main/Dockerfile"
click node_node_tests "https://github.com/thought-eater/tabu-search-tasf/blob/main/src/test/java/pe/edu/pucp/tasf/api/controller/RoutesControllerIntegrationTest.java"

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_main,node_node_ops,node_node_tests toneBlue
class node_node_api_ctrl,node_node_api_dto toneAmber
class node_node_model_network,node_node_flight,node_node_solution,node_node_tabu,node_node_config toneMint
class node_node_builder,node_node_loaders toneRose
class node_node_dbrepo,node_node_migrations toneIndigo
class node_node_mapper,node_node_simsvc,node_node_import,node_node_solver_orch,node_node_solver_state toneTeal
```

## Components

### CLI

Long-running simulation and experiment entrypoints

- [Main](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/Main.java): CLI modes · Runs E1, E2, E3, and EXP simulation modes · `src/main/java/pe/edu/pucp/tasf/Main.java`

### API

Spring Boot controllers and HTTP-facing contracts

- [API controllers](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/api/controller/RoutesController.java): HTTP resources · Airport, flight, shipment, routes, simulation, and solver endpoints · `src/main/java/pe/edu/pucp/tasf/api/controller/RoutesController.java`
- [DTO layer](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/api/dto/RoutesSolveResponse.java): request/response · HTTP-facing request and response shapes · `src/main/java/pe/edu/pucp/tasf/api/dto/RoutesSolveResponse.java`

### Core model

Shared logistics network and tabu search solver

- [Network model](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/model/LogisticsNetwork.java): domain graph · Airports, flights, shipment requests, route assignments, and solutions · `src/main/java/pe/edu/pucp/tasf/model/LogisticsNetwork.java`
- [Flight state](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/model/Flight.java): mutable capacity · Shared flight objects track in-place load across route searches · `src/main/java/pe/edu/pucp/tasf/model/Flight.java`
- [Route solution](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/model/Solution.java): assignment model · Represents complete shipment routing and feasibility outcome · `src/main/java/pe/edu/pucp/tasf/model/Solution.java`
- [Tabu solver](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/algorithm/TabuSearchSolver.java): search engine · Greedy init, tabu list, intensify/diversify, and replanning · `src/main/java/pe/edu/pucp/tasf/algorithm/TabuSearchSolver.java`
- [Solver config](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/algorithm/TabuSearchConfig.java): search config · Tuning and execution parameters for tabu search runs · `src/main/java/pe/edu/pucp/tasf/algorithm/TabuSearchConfig.java`

### Inputs

Text-file loaders and network assembly

- [Network builder](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/util/RealNetworkBuilder.java): network assembly · Builds the real logistics network from parsed inputs · `src/main/java/pe/edu/pucp/tasf/util/RealNetworkBuilder.java`
- [Text loaders](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/io/RealFlightLoader.java): file parsers · Parses airports, flights, and shipment text files · `src/main/java/pe/edu/pucp/tasf/io/RealFlightLoader.java`

### Persistence

Database schema, rows, and repository boundary

- [DB repo](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/db/SimulationDbRepository.java): data access · Database boundary used by simulation and solver-control services · `src/main/java/pe/edu/pucp/tasf/service/db/SimulationDbRepository.java`
- [Migrations](https://github.com/thought-eater/tabu-search-tasf/blob/main/migrations/0001_create_airports_table.up.sql): schema DDL · Creates and seeds airports, flights, shipments, assignments, and solver control tables · `migrations/0001_create_airports_table.up.sql`

### Services

Application services, orchestration, and mapping

- [API mapper](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/ApiMapper.java): translation · Bridges domain, persistence, and DTO representations · `src/main/java/pe/edu/pucp/tasf/service/ApiMapper.java`
- [Simulation svc](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/SimulationDataService.java): application service · Coordinates shipment import, simulation data, and state tracking · `src/main/java/pe/edu/pucp/tasf/service/SimulationDataService.java`
- [Import service](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/ShipmentImportService.java): ingestion service · Turns shipment text data into solver-ready records · `src/main/java/pe/edu/pucp/tasf/service/ShipmentImportService.java`
- [Solver orch](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/solver/TabuSolverOrchestratorService.java): orchestration · Runs solver workflows from API and simulation control · `src/main/java/pe/edu/pucp/tasf/service/solver/TabuSolverOrchestratorService.java`
- [Solver state](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/main/java/pe/edu/pucp/tasf/service/SolverState.java): control state · Tracks solver control status independent of controllers · `src/main/java/pe/edu/pucp/tasf/service/SolverState.java`

### Ops

Containerization, database bootstrap, and testing

- [Runtime ops](https://github.com/thought-eater/tabu-search-tasf/tree/main/Dockerfile): docker+bootstrap · Containerization and database initialization support · `Dockerfile`
- [Tests](https://github.com/thought-eater/tabu-search-tasf/blob/main/src/test/java/pe/edu/pucp/tasf/api/controller/RoutesControllerIntegrationTest.java): integration tests · Controller, service, and solver integration coverage plus smoke runner · `src/test/java/pe/edu/pucp/tasf/api/controller/RoutesControllerIntegrationTest.java`

## Connections

- Main → Network builder: builds network · CLI modes assemble the real network before solving
- Main → Tabu solver: runs solver · Simulation modes invoke the shared tabu search engine
- Text loaders → Network builder: parsed by · Text files are parsed into domain inputs consumed by the builder
- Network builder → Network model: creates · Builder assembles the logistics network graph
- Network model → Flight state: contains · Network owns shared flight instances with mutable loads
- Network model → Route solution: yields · Solver works over complete solution objects
- Tabu solver → Solver config: configured by · Search behavior comes from TabuSearchConfig
- Tabu solver → Network model: searches · Solver explores routes within the logistics network
- Tabu solver → Route solution: produces · Solver returns feasible or penalized route solutions
- Tabu solver → Flight state: updates capacity · Search mutates flight loads and requires resets before reruns
- API controllers → DTO layer: returns · Controllers expose DTOs instead of raw domain objects
- API controllers → API mapper: uses · HTTP resources delegate object conversion to the mapper
- API controllers → Solver orch: coordinates · Route and solver endpoints trigger orchestration workflows
- API controllers → Simulation svc: queries · Simulation endpoints read current simulation state
- API mapper → Network model: maps domain · Mapper bridges network and shipment representations
- Simulation svc → Import service: imports · Simulation layer ingests shipment files into records
- Simulation svc → Solver state: tracks · Service maintains solver/control status
- Solver orch → Tabu solver: executes · Orchestrator invokes tabu search and replanning runs
- Solver orch → DB repo: reads/writes · Solver control and simulation outcomes use the DB boundary
- DB repo → Migrations: backed by · Repository operates on the migrated schema
- Runtime ops → Migrations: boots db · Bootstrap scripts support migration-driven initialization
- Tests → API controllers: covers · Integration tests exercise controller boundaries
- Tests → Solver orch: covers · Tests validate solver orchestration behavior
- Tests → Main: covers · Smoke runner and end-to-end executions validate CLI flows