# mctop4ik/yamapapp architecture

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

- Interactive diagram: https://gitdiagram.com/mctop4ik/yamapapp
- Repository: https://github.com/mctop4ik/yamapapp

## Overview

#### Purpose and Entry Point
This is a C++ thread-planning service/CLI that retrieves station and search data, maps responses into domain flights/threads, and produces planned travel threads. The executable starts at `bin/main.cc`; build composition is defined in `CMakeLists.txt`.

#### Domain Model
Core business objects represent flights and candidate travel threads:
- `lib/domain/flight.hpp`
- `lib/domain/thread.hpp`

The repository abstraction separates planning logic from the data source:
- `lib/domain/repository-interface.hpp`

#### Application Layer
The application layer coordinates data retrieval and thread planning:
- `lib/application/thread-planner-service.hpp`
- `lib/application/repository.hpp`
- `lib/application/json-to-thread-vector-mapper.hpp`

`thread-planner-service` is the primary use-case boundary: it consumes repository-provided data and constructs/returns thread-oriented results. The mapper adapts stored or received JSON into domain thread vectors.

#### Presentation Boundary
A controller exposes the planning use case to the executable-facing layer:
- `lib/presentation/thread-controller.hpp`
- `bin/main.cc`

Control likely flows from `main` through the controller into `ThreadPlannerService`, keeping command/input handling outside domain and application logic.

#### Infrastructure Request Pipeline
Infrastructure implements endpoint access as middleware/request chains:
- `lib/infrastructure/search-request-chain.hpp`
- `lib/infrastructure/all-stations-request-chain.hpp`
- `lib/infrastructure/base-middleware.hpp`

Search and station retrieval are separate pipelines. Middleware supports cross-cutting stages including cached data, JSON acquisition, and prefetching:
- `lib/infrastructure/cache-middleware.hpp`
- `lib/infrastructure/json-provider-middleware.hpp`
- `lib/infrastructure/prefetch-data-middleware.hpp`

#### External Data, Mapping, and Storage
The system integrates with an HTTP-style external station/search API through endpoint abstractions:
- `lib/infrastructure/endpoint-interface.hpp`
- `lib/infrastructure/search-endpoint.hpp`
- `lib/infrastructure/all-stations-endpoint.hpp`

Request/response boundaries are explicit:
- `lib/infrastructure/http-request-dto.hpp`
- `lib/infrastructure/search-response-mapper.hpp`
- `lib/infrastructure/all-stations-mapper.hpp`

JSON persistence/caching is encapsulated in `lib/infrastructure/json-storage.hpp` and `lib/infrastructure/lru-cache.hpp`. API-token absence is modeled as a dedicated infrastructure failure in `lib/infrastructure/no-api-token-exception.hpp`.

#### Runtime Concerns
The runtime is a native C++ executable built with CMake. Logging and date handling are infrastructure services:
- `lib/infrastructure/logger.hpp`
- `lib/infrastructure/date-utils.hpp`
- `lib/application/config.hpp`

The key architectural boundary is domain/application code depending on repository and endpoint interfaces, while concrete HTTP, JSON, cache, and API-token concerns remain in infrastructure.

Main entry points: [`lib/application/repository.hpp`](https://github.com/mctop4ik/yamapapp/blob/master/lib/application/repository.hpp) (Application repository), [`lib/infrastructure/search-endpoint.hpp`](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/search-endpoint.hpp) (Search endpoint), [`lib/application/thread-planner-service.hpp`](https://github.com/mctop4ik/yamapapp/blob/master/lib/application/thread-planner-service.hpp) (Thread planner service), [`lib/infrastructure/all-stations-endpoint.hpp`](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/all-stations-endpoint.hpp) (Stations endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["CLI executable<br/>C++ entry point<br/>[main.cc]"]
  node_cmake["CMake build<br/>build definition<br/>[CMakeLists.txt]"]
end

subgraph group_presentation["Presentation"]
  node_controller["Thread controller"]
end

subgraph group_application["Application"]
  node_planner["Thread planner service<br/>use case"]
  node_repository["Application repository<br/>data access adapter<br/>[repository.hpp]"]
  node_thread_mapper["JSON thread mapper"]
  node_config["Application config<br/>configuration<br/>[config.hpp]"]
end

subgraph group_domain["Domain"]
  node_flight["Flight<br/>domain model<br/>[flight.hpp]"]
  node_thread["Travel thread<br/>domain model<br/>[thread.hpp]"]
  node_repository_interface{{"Repository interface<br/>port"}}
end

subgraph group_infrastructure["Infrastructure"]
  node_search_chain["Search request chain<br/>request pipeline"]
  node_stations_chain["Stations request chain<br/>request pipeline"]
  node_middleware{{"Base middleware<br/>middleware abstraction"}}
  node_data_middleware["Cache, JSON &amp; prefetch<br/>middleware stages"]
  node_endpoint_interface{{"Endpoint interface<br/>port"}}
  node_search_endpoint["Search endpoint<br/>HTTP endpoint"]
  node_stations_endpoint["Stations endpoint<br/>HTTP endpoint"]
  node_response_mappers["Response mappers<br/>DTO mapper"]
  node_json_storage[("JSON storage<br/>persistence/cache storage<br/>[json-storage.hpp]")]
  node_lru_cache[("LRU cache<br/>[lru-cache.hpp]")]
  node_http_request["HTTP request DTO"]
  node_runtime_services["Logging, dates &amp; token failure<br/>runtime support<br/>[logger.hpp]"]
end

node_cmake -->|"builds"| node_main
node_main -->|"invokes"| node_controller
node_controller -->|"plans threads"| node_planner
node_planner -->|"retrieves through"| node_repository_interface
node_planner -->|"returns"| node_thread
node_planner -->|"plans from"| node_flight
node_repository -->|"implements"| node_repository_interface
node_repository -->|"requests search data"| node_search_chain
node_repository -->|"requests station data"| node_stations_chain
node_repository -->|"maps JSON"| node_thread_mapper
node_thread_mapper -->|"creates vectors of"| node_thread
node_search_chain -->|"composes"| node_middleware
node_stations_chain -->|"composes"| node_middleware
node_middleware -->|"base for"| node_data_middleware
node_data_middleware -->|"persists JSON"| node_json_storage
node_data_middleware -->|"uses"| node_lru_cache
node_search_chain -->|"calls"| node_search_endpoint
node_stations_chain -->|"calls"| node_stations_endpoint
node_search_endpoint -->|"implements"| node_endpoint_interface
node_stations_endpoint -->|"implements"| node_endpoint_interface
node_search_endpoint -->|"uses"| node_http_request
node_stations_endpoint -->|"uses"| node_http_request
node_search_endpoint -->|"maps response"| node_response_mappers
node_stations_endpoint -->|"maps response"| node_response_mappers
node_repository -->|"reads"| node_config
node_search_endpoint -.->|"uses"| node_runtime_services

click node_main "https://github.com/mctop4ik/yamapapp/blob/master/bin/main.cc"
click node_controller "https://github.com/mctop4ik/yamapapp/blob/master/lib/presentation/thread-controller.hpp"
click node_planner "https://github.com/mctop4ik/yamapapp/blob/master/lib/application/thread-planner-service.hpp"
click node_repository "https://github.com/mctop4ik/yamapapp/blob/master/lib/application/repository.hpp"
click node_thread_mapper "https://github.com/mctop4ik/yamapapp/blob/master/lib/application/json-to-thread-vector-mapper.hpp"
click node_config "https://github.com/mctop4ik/yamapapp/blob/master/lib/application/config.hpp"
click node_flight "https://github.com/mctop4ik/yamapapp/blob/master/lib/domain/flight.hpp"
click node_thread "https://github.com/mctop4ik/yamapapp/blob/master/lib/domain/thread.hpp"
click node_repository_interface "https://github.com/mctop4ik/yamapapp/blob/master/lib/domain/repository-interface.hpp"
click node_search_chain "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/search-request-chain.hpp"
click node_stations_chain "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/all-stations-request-chain.hpp"
click node_middleware "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/base-middleware.hpp"
click node_data_middleware "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/cache-middleware.hpp"
click node_endpoint_interface "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/endpoint-interface.hpp"
click node_search_endpoint "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/search-endpoint.hpp"
click node_stations_endpoint "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/all-stations-endpoint.hpp"
click node_response_mappers "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/search-response-mapper.hpp"
click node_json_storage "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/json-storage.hpp"
click node_lru_cache "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/lru-cache.hpp"
click node_http_request "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/http-request-dto.hpp"
click node_runtime_services "https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/logger.hpp"
click node_cmake "https://github.com/mctop4ik/yamapapp/blob/master/CMakeLists.txt"

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_main,node_cmake toneBlue
class node_controller toneAmber
class node_planner,node_repository,node_thread_mapper,node_config toneMint
class node_flight,node_thread,node_repository_interface toneRose
class node_search_chain,node_stations_chain,node_middleware,node_data_middleware,node_endpoint_interface,node_search_endpoint,node_stations_endpoint,node_response_mappers,node_json_storage,node_lru_cache,node_http_request,node_runtime_services toneIndigo
```

## Components

### Runtime

- [CLI executable](https://github.com/mctop4ik/yamapapp/blob/master/bin/main.cc): C++ entry point · `bin/main.cc`
- [CMake build](https://github.com/mctop4ik/yamapapp/blob/master/CMakeLists.txt): build definition · `CMakeLists.txt`

### Presentation

- [Thread controller](https://github.com/mctop4ik/yamapapp/blob/master/lib/presentation/thread-controller.hpp): controller · `lib/presentation/thread-controller.hpp`

### Application

- [Thread planner service](https://github.com/mctop4ik/yamapapp/blob/master/lib/application/thread-planner-service.hpp): use case · Coordinates retrieval and planned-thread construction. · `lib/application/thread-planner-service.hpp`
- [Application repository](https://github.com/mctop4ik/yamapapp/blob/master/lib/application/repository.hpp): data access adapter · `lib/application/repository.hpp`
- [JSON thread mapper](https://github.com/mctop4ik/yamapapp/blob/master/lib/application/json-to-thread-vector-mapper.hpp): mapper · `lib/application/json-to-thread-vector-mapper.hpp`
- [Application config](https://github.com/mctop4ik/yamapapp/blob/master/lib/application/config.hpp): configuration · `lib/application/config.hpp`

### Domain

- [Flight](https://github.com/mctop4ik/yamapapp/blob/master/lib/domain/flight.hpp): domain model · `lib/domain/flight.hpp`
- [Travel thread](https://github.com/mctop4ik/yamapapp/blob/master/lib/domain/thread.hpp): domain model · `lib/domain/thread.hpp`
- [Repository interface](https://github.com/mctop4ik/yamapapp/blob/master/lib/domain/repository-interface.hpp): port · Separates planning from data-source implementation. · `lib/domain/repository-interface.hpp`

### Infrastructure

- [Search request chain](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/search-request-chain.hpp): request pipeline · `lib/infrastructure/search-request-chain.hpp`
- [Stations request chain](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/all-stations-request-chain.hpp): request pipeline · `lib/infrastructure/all-stations-request-chain.hpp`
- [Base middleware](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/base-middleware.hpp): middleware abstraction · `lib/infrastructure/base-middleware.hpp`
- [Cache, JSON & prefetch](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/cache-middleware.hpp): middleware stages · Cross-cutting cached-data, JSON-acquisition, and prefetch stages. · `lib/infrastructure/cache-middleware.hpp`
- [Endpoint interface](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/endpoint-interface.hpp): port · `lib/infrastructure/endpoint-interface.hpp`
- [Search endpoint](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/search-endpoint.hpp): HTTP endpoint · `lib/infrastructure/search-endpoint.hpp`
- [Stations endpoint](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/all-stations-endpoint.hpp): HTTP endpoint · `lib/infrastructure/all-stations-endpoint.hpp`
- [Response mappers](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/search-response-mapper.hpp): DTO mapper · Maps search and station API responses. · `lib/infrastructure/search-response-mapper.hpp`
- [JSON storage](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/json-storage.hpp): persistence/cache storage · `lib/infrastructure/json-storage.hpp`
- [LRU cache](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/lru-cache.hpp): cache · `lib/infrastructure/lru-cache.hpp`
- [HTTP request DTO](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/http-request-dto.hpp): request DTO · `lib/infrastructure/http-request-dto.hpp`
- [Logging, dates & token failure](https://github.com/mctop4ik/yamapapp/blob/master/lib/infrastructure/logger.hpp): runtime support · Provides logging/date utilities and models missing API-token failure. · `lib/infrastructure/logger.hpp`

## Connections

- CMake build → CLI executable: builds
- CLI executable → Thread controller: invokes
- Thread controller → Thread planner service: plans threads
- Thread planner service → Repository interface: retrieves through
- Thread planner service → Travel thread: returns
- Thread planner service → Flight: plans from
- Application repository → Repository interface: implements
- Application repository → Search request chain: requests search data
- Application repository → Stations request chain: requests station data
- Application repository → JSON thread mapper: maps JSON
- JSON thread mapper → Travel thread: creates vectors of
- Search request chain → Base middleware: composes
- Stations request chain → Base middleware: composes
- Base middleware → Cache, JSON & prefetch: base for
- Cache, JSON & prefetch → JSON storage: persists JSON
- Cache, JSON & prefetch → LRU cache: uses
- Search request chain → Search endpoint: calls
- Stations request chain → Stations endpoint: calls
- Search endpoint → Endpoint interface: implements
- Stations endpoint → Endpoint interface: implements
- Search endpoint → HTTP request DTO: uses
- Stations endpoint → HTTP request DTO: uses
- Search endpoint → Response mappers: maps response
- Stations endpoint → Response mappers: maps response
- Application repository → Application config: reads
- Search endpoint → Logging, dates & token failure: uses