How veaglev/algorithm-service works
This repository is a single-module Java service built with Maven and Spring Boot. The main application entry point is CoreApplication, and the code is organized under com.crm.algo.core, which suggests a backend service rather than a library or UI.
1. API boundary
- controllers/AlgoController is the outward-facing entry point.
- It likely accepts request DTOs such as AlgoRequest and ShipmentRequest, then returns response DTOs like RouteResponse, SpanResponse, WarehouseResponse, TransportResponse, and ItemListResponse.
- This controller layer is the external contract for the service.
2. Application/service orchestration
- services/AlgoService appears to be the orchestration layer that coordinates the core algorithm and the domain services.
- Supporting services split responsibilities by domain concern: ItemListService, RouteService, SpanService, TransportService, and WarehouseService.
- This separation suggests a layered design where the controller delegates to services, and services manage business rules and persistence.
3. Core algorithm subsystem
- algos/TheWay is the most likely algorithm implementation class.
- It probably contains the main decision logic for route/span/transport selection, while the service layer handles input validation, coordination, and output shaping.
- This is the heart of the repository’s business value.
4. Domain and persistence model
- entity/Route and entity/Span are the persistent domain entities.
- repositories/RouteRepository and repositories/SpanRepository are the persistence boundaries, likely Spring Data repositories.
- The architecture implies a database-backed service, with repositories mediating access to stored route/span data.
5. Transformation layer
- mappers/SpanMapper converts between Span entities and SpanResponse DTOs.
- This indicates a deliberate separation between persistence models and API models, which helps keep the external API stable even if the database schema changes.
6. Internal non-persistent model
- models/TransportModel is an internal domain model used for transport-related calculations or aggregation.
- It likely exists to represent computed state that does not map directly to a database table or API contract.
7. Domain vocabulary
- enums/Condition, Type, and TransportType define controlled domain values.
- These enums help constrain business logic and prevent invalid states across the algorithm and service layers.
8. Error handling
- exceptions/NotEnoughItemsException and NotEnoughTransportsException are explicit business exceptions.
- They suggest the system validates availability constraints and fails fast when required resources are insufficient.
- These exceptions likely propagate from services back to the controller for API-level error responses.
9. Data flow
- Typical flow is: request enters AlgoController → service layer validates and coordinates → core algorithm in TheWay computes the result → repositories fetch/update route/span data → mappers and DTOs shape the response.
- This is a classic controller-service-repository architecture with a separate algorithm engine in the middle.
10. Runtime and packaging
- The presence of Dockerfile, Maven wrapper files, and application.properties indicates the service is meant to be built and run in a containerized deployment.
- The architecture is therefore oriented around a deployable backend service rather than an embedded algorithm module.
11. Testing surface
- CoreApplicationTests shows at least a minimal Spring Boot test harness.
- The repository currently appears light on test breadth, so the main architectural understanding comes from package structure rather than extensive test fixtures.
Overall, the system is a Spring Boot algorithm service with a clear separation between API, orchestration, algorithm logic, persistence, and DTO mapping. If you draw it, the main boundaries are: controller/API, service orchestration, core algorithm, persistence/repositories, and supporting domain types/exceptions.
Main entry points: AlgoService.java Algo service · AlgoController.java Algo API · TheWay.java TheWay · SpanService.java Span service
Components 17
Boot
Application entry and runtime bootstrap
- Core app · Main application bootstrap
core/src/main/java/com/crm/algo/core/CoreApplication.java
API
External request and response boundary
- Algo API · External request handling boundary
core/src/main/java/com/crm/algo/core/controllers/AlgoController.java
Services
Orchestration and domain services
- Algo service · Coordinates algorithm execution and domain services
core/src/main/java/com/crm/algo/core/services/AlgoService.java - Item list · Handles item list rules and availability
core/src/main/java/com/crm/algo/core/services/ItemListService.java - Route service · Manages route-related business logic
core/src/main/java/com/crm/algo/core/services/RouteService.java - Span service · Coordinates span processing and mapping
core/src/main/java/com/crm/algo/core/services/SpanService.java - Transport service · Handles transport selection and constraints
core/src/main/java/com/crm/algo/core/services/TransportService.java - Warehouse service · Handles warehouse-related business logic
core/src/main/java/com/crm/algo/core/services/WarehouseService.java
Algorithm
Core decision logic
- TheWay · Core algorithm and decision logic
core/src/main/java/com/crm/algo/core/algos/TheWay.java
Data
Persistence and mapping boundary
- Route repo · Persistence access for routes
core/src/main/java/com/crm/algo/core/repositories/RouteRepository.java - Span repo · Persistence access for spans
core/src/main/java/com/crm/algo/core/repositories/SpanRepository.java - Span mapper · Converts span entities to response DTOs
core/src/main/java/com/crm/algo/core/mappers/SpanMapper.java - Route · Persistent route model
core/src/main/java/com/crm/algo/core/entity/Route.java - Span · Persistent span model
core/src/main/java/com/crm/algo/core/entity/Span.java
Domain
Shared domain types and exceptions
- Transport model · Internal transport calculation model
core/src/main/java/com/crm/algo/core/models/TransportModel.java - Domain enums · Controlled values for conditions, types, and transport types
- Business errors · Availability and constraint failures
Connections 25
- Core app → Algo API: starts · Bootstraps the web service
- Algo API → Algo service: delegates · Controller passes requests into orchestration
- Algo API → Route service: uses · Controller may expose route-related operations
- Algo API → Span service: uses · Controller may expose span-related operations
- Algo API → Transport service: uses · Controller may expose transport-related operations
- Algo API → Warehouse service: uses · Controller may expose warehouse-related operations
- Algo service → TheWay: executes · Orchestration invokes the core algorithm
- Algo service → Item list: coordinates · Handles item availability and business rules
- Algo service → Route service: coordinates · Coordinates route lookup and updates
- Algo service → Span service: coordinates · Coordinates span processing
- Algo service → Transport service: coordinates · Coordinates transport logic
- Algo service → Warehouse service: coordinates · Coordinates warehouse logic
- TheWay → Route repo: reads · Algorithm consults route data
- TheWay → Span repo: reads · Algorithm consults span data
- TheWay → Transport model: builds · Produces computed transport state
- Route service → Route repo: persists · Route service uses repository boundary
- Span service → Span repo: persists · Span service uses repository boundary
- Span service → Span mapper: maps · Converts entity data into response shape
- Route repo → Route: stores · Repository manages route entities
- Span repo → Span: stores · Repository manages span entities
- Item list → Business errors: throws · Signals insufficient items
- Transport service → Business errors: throws · Signals insufficient transports
- Algo service → Domain enums: depends on · Business rules use domain-controlled values
- TheWay → Domain enums: depends on · Algorithm branches on controlled values
- Transport service → Domain enums: depends on · Transport logic uses domain-controlled values