thought-eater/tabu-search-tasf

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.