# veaglev/algorithm-service architecture

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

- Interactive diagram: https://gitdiagram.com/veaglev/algorithm-service
- Repository: https://github.com/veaglev/algorithm-service

## Overview

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: [`core/src/main/java/com/crm/algo/core/services/AlgoService.java`](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/AlgoService.java) (Algo service), [`core/src/main/java/com/crm/algo/core/controllers/AlgoController.java`](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/controllers/AlgoController.java) (Algo API), [`core/src/main/java/com/crm/algo/core/algos/TheWay.java`](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/algos/TheWay.java) (TheWay), [`core/src/main/java/com/crm/algo/core/services/SpanService.java`](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/SpanService.java) (Span service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["Boot"]
  node_n_app(("Core app<br/>Spring Boot entry"))
end

subgraph group_g_api["API"]
  node_n_controller["Algo API<br/>REST controller"]
end

subgraph group_g_service["Services"]
  node_n_algo_service["Algo service<br/>orchestrator<br/>[AlgoService.java]"]
  node_n_item_service["Item list<br/>domain service"]
  node_n_route_service["Route service<br/>domain service<br/>[RouteService.java]"]
  node_n_span_service["Span service<br/>domain service<br/>[SpanService.java]"]
  node_n_transport_service["Transport service<br/>domain service"]
  node_n_warehouse_service["Warehouse service<br/>domain service"]
end

subgraph group_g_algo["Algorithm"]
  node_n_way{{"TheWay<br/>algorithm engine<br/>[TheWay.java]"}}
end

subgraph group_g_data["Data"]
  node_n_route_repo[("Route repo<br/>persistence repository")]
  node_n_span_repo[("Span repo<br/>persistence repository")]
  node_n_span_mapper["Span mapper<br/>dto mapper<br/>[SpanMapper.java]"]
  node_n_route_entity["Route<br/>entity<br/>[Route.java]"]
  node_n_span_entity["Span<br/>entity<br/>[Span.java]"]
end

subgraph group_g_domain["Domain"]
  node_n_transport_model["Transport model<br/>computed model"]
  node_n_enums{{"Domain enums<br/>enum set"}}
  node_n_exceptions(("Business errors<br/>exceptions"))
end

node_n_app -->|"starts"| node_n_controller
node_n_controller -->|"delegates"| node_n_algo_service
node_n_controller -.->|"uses"| node_n_route_service
node_n_controller -.->|"uses"| node_n_span_service
node_n_controller -.->|"uses"| node_n_transport_service
node_n_controller -.->|"uses"| node_n_warehouse_service
node_n_algo_service -->|"executes"| node_n_way
node_n_algo_service -->|"coordinates"| node_n_item_service
node_n_algo_service -->|"coordinates"| node_n_route_service
node_n_algo_service -->|"coordinates"| node_n_span_service
node_n_algo_service -->|"coordinates"| node_n_transport_service
node_n_algo_service -->|"coordinates"| node_n_warehouse_service
node_n_way -->|"reads"| node_n_route_repo
node_n_way -->|"reads"| node_n_span_repo
node_n_way -->|"builds"| node_n_transport_model
node_n_route_service -->|"persists"| node_n_route_repo
node_n_span_service -->|"persists"| node_n_span_repo
node_n_span_service -->|"maps"| node_n_span_mapper
node_n_route_repo -->|"stores"| node_n_route_entity
node_n_span_repo -->|"stores"| node_n_span_entity
node_n_item_service -->|"throws"| node_n_exceptions
node_n_transport_service -->|"throws"| node_n_exceptions
node_n_algo_service -.->|"depends on"| node_n_enums
node_n_way -.->|"depends on"| node_n_enums
node_n_transport_service -.->|"depends on"| node_n_enums

click node_n_app "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/CoreApplication.java"
click node_n_controller "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/controllers/AlgoController.java"
click node_n_algo_service "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/AlgoService.java"
click node_n_item_service "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/ItemListService.java"
click node_n_route_service "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/RouteService.java"
click node_n_span_service "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/SpanService.java"
click node_n_transport_service "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/TransportService.java"
click node_n_warehouse_service "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/WarehouseService.java"
click node_n_way "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/algos/TheWay.java"
click node_n_route_repo "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/repositories/RouteRepository.java"
click node_n_span_repo "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/repositories/SpanRepository.java"
click node_n_span_mapper "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/mappers/SpanMapper.java"
click node_n_route_entity "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/entity/Route.java"
click node_n_span_entity "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/entity/Span.java"
click node_n_transport_model "https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/models/TransportModel.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_n_app toneBlue
class node_n_controller toneAmber
class node_n_algo_service,node_n_item_service,node_n_route_service,node_n_span_service,node_n_transport_service,node_n_warehouse_service toneMint
class node_n_way toneRose
class node_n_route_repo,node_n_span_repo,node_n_span_mapper,node_n_route_entity,node_n_span_entity toneIndigo
class node_n_transport_model,node_n_enums,node_n_exceptions toneTeal
```

## Components

### Boot

Application entry and runtime bootstrap

- [Core app](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/CoreApplication.java): Spring Boot entry · Main application bootstrap · `core/src/main/java/com/crm/algo/core/CoreApplication.java`

### API

External request and response boundary

- [Algo API](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/controllers/AlgoController.java): REST controller · External request handling boundary · `core/src/main/java/com/crm/algo/core/controllers/AlgoController.java`

### Services

Orchestration and domain services

- [Algo service](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/AlgoService.java): orchestrator · Coordinates algorithm execution and domain services · `core/src/main/java/com/crm/algo/core/services/AlgoService.java`
- [Item list](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/ItemListService.java): domain service · Handles item list rules and availability · `core/src/main/java/com/crm/algo/core/services/ItemListService.java`
- [Route service](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/RouteService.java): domain service · Manages route-related business logic · `core/src/main/java/com/crm/algo/core/services/RouteService.java`
- [Span service](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/SpanService.java): domain service · Coordinates span processing and mapping · `core/src/main/java/com/crm/algo/core/services/SpanService.java`
- [Transport service](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/TransportService.java): domain service · Handles transport selection and constraints · `core/src/main/java/com/crm/algo/core/services/TransportService.java`
- [Warehouse service](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/services/WarehouseService.java): domain service · Handles warehouse-related business logic · `core/src/main/java/com/crm/algo/core/services/WarehouseService.java`

### Algorithm

Core decision logic

- [TheWay](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/algos/TheWay.java): algorithm engine · Core algorithm and decision logic · `core/src/main/java/com/crm/algo/core/algos/TheWay.java`

### Data

Persistence and mapping boundary

- [Route repo](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/repositories/RouteRepository.java): persistence repository · Persistence access for routes · `core/src/main/java/com/crm/algo/core/repositories/RouteRepository.java`
- [Span repo](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/repositories/SpanRepository.java): persistence repository · Persistence access for spans · `core/src/main/java/com/crm/algo/core/repositories/SpanRepository.java`
- [Span mapper](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/mappers/SpanMapper.java): dto mapper · Converts span entities to response DTOs · `core/src/main/java/com/crm/algo/core/mappers/SpanMapper.java`
- [Route](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/entity/Route.java): entity · Persistent route model · `core/src/main/java/com/crm/algo/core/entity/Route.java`
- [Span](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/entity/Span.java): entity · Persistent span model · `core/src/main/java/com/crm/algo/core/entity/Span.java`

### Domain

Shared domain types and exceptions

- [Transport model](https://github.com/veaglev/algorithm-service/blob/main/core/src/main/java/com/crm/algo/core/models/TransportModel.java): computed model · Internal transport calculation model · `core/src/main/java/com/crm/algo/core/models/TransportModel.java`
- **Domain enums**: enum set · Controlled values for conditions, types, and transport types
- **Business errors**: exceptions · Availability and constraint failures

## Connections

- 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