# xd-cods/cab-aggregator architecture

> Architecture diagram of the GitHub repository xd-cods/cab-aggregator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xd-cods/cab-aggregator
- Repository: https://github.com/xd-cods/cab-aggregator

## Overview

#### Purpose and Runtime Topology
Umi is a Java 17/Spring Boot 3.4 Spring Cloud taxi-platform monorepo. It runs independently deployable services for identity, passenger and driver profiles, rides, and ratings. Each service is a Maven/Spring Boot entry point, e.g. `ride-service/src/main/java/com/vlad/kuzhyr/rideservice/RideServiceApplication.java`; the root `pom.xml` coordinates the repository.

#### Platform Control Plane
Centralized configuration is served by `config-server/src/main/java/com/vlad/kuzhyr/configserver/ConfigServerApplication.java`, with service-specific configuration stored under `config-server/src/main/resources/config/`. Service registration/discovery is provided by `eureka-server/src/main/java/com/vlad/kuzhyr/eurkeserver/EurekaServerApplication.java`. This creates the startup dependency chain: configuration/discovery must be available before routed and inter-service traffic is reliable.

#### API Edge and Security Boundary
External API traffic enters the gateway at `api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/ApiGatewayApplication.java`. Its security policy and user-identity propagation are implemented in `api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/config/SecurityConfig.java` and `api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/config/filter/AddUserIdHeaderFilter.java`. Downstream services each have security configurations and JWT converters, making the gateway the routing boundary but not the sole authorization boundary.

#### Identity and Profile Provisioning
`auth-service` manages sign-up/sign-in, refresh, and business-role assignment through `auth-service/src/main/java/com/vlad/kuzhyr/authservice/web/controller/impl/UserControllerImpl.java`. It delegates identity operations to Keycloak via `auth-service/src/main/java/com/vlad/kuzhyr/authservice/service/impl/KeycloakAuthServiceImpl.java` and synchronously provisions or coordinates driver/passenger profiles through Feign clients in `auth-service/src/main/java/com/vlad/kuzhyr/authservice/utility/client/`. Keycloak is the OAuth2/OIDC authority; profile data belongs to separate domain services.

#### Driver and Passenger Domains
Driver ownership includes drivers, cars, and busy state, persisted through `driver-service/src/main/java/com/vlad/kuzhyr/driverservice/persistence/entity/Driver.java` and `driver-service/src/main/java/com/vlad/kuzhyr/driverservice/persistence/entity/Car.java`. Passenger ownership is isolated in `passenger-service/src/main/java/com/vlad/kuzhyr/passengerservice/persistence/entity/Passenger.java`. Both expose REST controllers and consume Kafka events through processor/listener pairs, such as `driver-service/src/main/java/com/vlad/kuzhyr/driverservice/utility/broker/DriverEventListener.java` and `passenger-service/src/main/java/com/vlad/kuzhyr/passengerservice/utility/broker/PassengerProcessor.java`.

#### Ride Lifecycle, Geospatial Integration, and Events
`ride-service` is the orchestration core: it validates and transitions rides in `ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/RideServiceImpl.java`, calls driver/passenger services through Feign clients, and calls Mapbox through `ride-service/src/main/java/com/vlad/kuzhyr/rideservice/utility/client/MapboxClient.java` for address/distance input. It caches address data via `ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/cache/AddressCacheService.java`. Ride changes are durably staged in the `KafkaMessage` outbox entity and dispatched by `KafkaMessageScheduler`/`RideEventProducer`, separating transactional ride updates from asynchronous publication.

#### Ratings and Event-Driven Completion
`rating-service` owns ratings plus received ride snapshots (`Rating` and `RideInfo`) under `rating-service/src/main/java/com/vlad/kuzhyr/ratingservice/persistence/entity/`. `RatingEventListener` consumes ride-related Kafka payloads, allowing ratings and average-rating queries to operate on locally persisted ride context rather than requiring synchronous ride lookups.

#### Data and Operations
Passenger, driver, ride, and rating services use isolated PostgreSQL schemas with Liquibase migrations; ride migrations include the outbox and scheduler-lock tables under `ride-service/src/main/resources/db/changelog/`. Redis supports caching/geospatial concerns, Kafka supplies event streaming, and Docker Compose is the local deployment definition at `docker/docker-compose.yml`. Keycloak realm bootstrap is `docker/realm-export.json`; observability assets include Prometheus, Grafana, Loki, Promtail, and Tempo configurations under `docker/`.

Main entry points: [`ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/RideServiceImpl.java`](https://github.com/xd-cods/cab-aggregator/blob/develop/ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/RideServiceImpl.java) (Ride Service), [`config-server/src/main/java/com/vlad/kuzhyr/configserver/ConfigServerApplication.java`](https://github.com/xd-cods/cab-aggregator/blob/develop/config-server/src/main/java/com/vlad/kuzhyr/configserver/ConfigServerApplication.java) (Config Server), [`api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/config/SecurityConfig.java`](https://github.com/xd-cods/cab-aggregator/blob/develop/api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/config/SecurityConfig.java) (Gateway Security), [`auth-service/src/main/java/com/vlad/kuzhyr/authservice/web/controller/impl/UserControllerImpl.java`](https://github.com/xd-cods/cab-aggregator/blob/develop/auth-service/src/main/java/com/vlad/kuzhyr/authservice/web/controller/impl/UserControllerImpl.java) (Auth Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Plane"]
  node_config["Config Server<br/>Spring Cloud config"]
  node_config_repo["Service Config<br/>configuration source"]
  node_discovery["Eureka Server<br/>service discovery"]
end

subgraph group_edge["API &amp; Identity"]
  node_gateway["API Gateway<br/>Spring Cloud gateway"]
  node_gateway_security["Gateway Security<br/>JWT filter policy"]
  node_auth["Auth Service<br/>identity provisioning service"]
  node_keycloak{{"Keycloak<br/>OAuth2/OIDC authority<br/>[realm-export.json]"}}
end

subgraph group_domains["Domain Services"]
  node_driver["Driver Service<br/>driver and car domain<br/>[Driver.java]"]
  node_passenger["Passenger Service<br/>passenger domain<br/>[Passenger.java]"]
  node_ride["Ride Service<br/>ride lifecycle orchestrator"]
  node_ride_outbox[("Ride Outbox<br/>transactional event staging")]
  node_rating["Rating Service<br/>rating domain"]
end

subgraph group_infra["Data &amp; Operations"]
  node_mapbox{{"Mapbox<br/>geospatial API<br/>[MapboxClient.java]"}}
  node_redis[("Redis<br/>cache and geospatial store")]
  node_kafka["Kafka<br/>event stream"]
  node_postgres[("PostgreSQL Schemas<br/>isolated service databases")]
  node_compose["Docker Compose<br/>local deployment<br/>[docker-compose.yml]"]
  node_observability["Observability Stack<br/>metrics logs traces"]
end

node_config_repo -->|"served by"| node_config
node_config -.->|"configuration"| node_gateway
node_config -.->|"configuration"| node_auth
node_config -.->|"configuration"| node_driver
node_config -.->|"configuration"| node_passenger
node_config -.->|"configuration"| node_ride
node_config -.->|"configuration"| node_rating
node_discovery -.->|"service discovery"| node_gateway
node_discovery -.->|"service discovery"| node_auth
node_discovery -.->|"service discovery"| node_ride
node_gateway -->|"applies"| node_gateway_security
node_gateway_security -->|"routes authenticated requests"| node_auth
node_gateway_security -->|"routes authenticated requests"| node_driver
node_gateway_security -->|"routes authenticated requests"| node_passenger
node_gateway_security -->|"routes authenticated requests"| node_ride
node_gateway_security -->|"routes authenticated requests"| node_rating
node_auth -->|"identity operations"| node_keycloak
node_auth -->|"provisions driver profiles"| node_driver
node_auth -->|"provisions passenger profiles"| node_passenger
node_ride -->|"Feign driver coordination"| node_driver
node_ride -->|"Feign passenger coordination"| node_passenger
node_ride -->|"address and distance"| node_mapbox
node_ride -->|"address cache"| node_redis
node_ride -->|"stages ride events"| node_ride_outbox
node_ride_outbox -->|"scheduled publication"| node_kafka
node_kafka -->|"driver events"| node_driver
node_kafka -->|"passenger events"| node_passenger
node_kafka -->|"ride snapshots"| node_rating
node_driver -->|"driver schema"| node_postgres
node_passenger -->|"passenger schema"| node_postgres
node_ride -->|"ride and outbox schema"| node_postgres
node_rating -->|"rating schema"| node_postgres
node_compose -.->|"local stack assets"| node_observability

click node_config "https://github.com/xd-cods/cab-aggregator/blob/develop/config-server/src/main/java/com/vlad/kuzhyr/configserver/ConfigServerApplication.java"
click node_discovery "https://github.com/xd-cods/cab-aggregator/blob/develop/eureka-server/src/main/java/com/vlad/kuzhyr/eurkeserver/EurekaServerApplication.java"
click node_gateway "https://github.com/xd-cods/cab-aggregator/blob/develop/api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/ApiGatewayApplication.java"
click node_gateway_security "https://github.com/xd-cods/cab-aggregator/blob/develop/api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/config/SecurityConfig.java"
click node_auth "https://github.com/xd-cods/cab-aggregator/blob/develop/auth-service/src/main/java/com/vlad/kuzhyr/authservice/web/controller/impl/UserControllerImpl.java"
click node_keycloak "https://github.com/xd-cods/cab-aggregator/blob/develop/docker/realm-export.json"
click node_driver "https://github.com/xd-cods/cab-aggregator/blob/develop/driver-service/src/main/java/com/vlad/kuzhyr/driverservice/persistence/entity/Driver.java"
click node_passenger "https://github.com/xd-cods/cab-aggregator/blob/develop/passenger-service/src/main/java/com/vlad/kuzhyr/passengerservice/persistence/entity/Passenger.java"
click node_ride "https://github.com/xd-cods/cab-aggregator/blob/develop/ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/RideServiceImpl.java"
click node_mapbox "https://github.com/xd-cods/cab-aggregator/blob/develop/ride-service/src/main/java/com/vlad/kuzhyr/rideservice/utility/client/MapboxClient.java"
click node_redis "https://github.com/xd-cods/cab-aggregator/blob/develop/ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/cache/AddressCacheService.java"
click node_compose "https://github.com/xd-cods/cab-aggregator/blob/develop/docker/docker-compose.yml"

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_config,node_config_repo,node_discovery toneBlue
class node_gateway,node_gateway_security,node_auth,node_keycloak toneAmber
class node_driver,node_passenger,node_ride,node_ride_outbox,node_rating toneMint
class node_mapbox,node_redis,node_kafka,node_postgres,node_compose,node_observability toneRose
```

## Components

### Control Plane

- [Config Server](https://github.com/xd-cods/cab-aggregator/blob/develop/config-server/src/main/java/com/vlad/kuzhyr/configserver/ConfigServerApplication.java): Spring Cloud config · Serves service-specific configuration. · `config-server/src/main/java/com/vlad/kuzhyr/configserver/ConfigServerApplication.java`
- **Service Config**: configuration source
- [Eureka Server](https://github.com/xd-cods/cab-aggregator/blob/develop/eureka-server/src/main/java/com/vlad/kuzhyr/eurkeserver/EurekaServerApplication.java): service discovery · `eureka-server/src/main/java/com/vlad/kuzhyr/eurkeserver/EurekaServerApplication.java`

### API & Identity

- [API Gateway](https://github.com/xd-cods/cab-aggregator/blob/develop/api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/ApiGatewayApplication.java): Spring Cloud gateway · External routing and identity propagation boundary. · `api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/ApiGatewayApplication.java`
- [Gateway Security](https://github.com/xd-cods/cab-aggregator/blob/develop/api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/config/SecurityConfig.java): JWT filter policy · `api-gateway/src/main/java/com/vlad/kuzhyr/apigateway/config/SecurityConfig.java`
- [Auth Service](https://github.com/xd-cods/cab-aggregator/blob/develop/auth-service/src/main/java/com/vlad/kuzhyr/authservice/web/controller/impl/UserControllerImpl.java): identity provisioning service · Signs users in and provisions domain profiles. · `auth-service/src/main/java/com/vlad/kuzhyr/authservice/web/controller/impl/UserControllerImpl.java`
- [Keycloak](https://github.com/xd-cods/cab-aggregator/blob/develop/docker/realm-export.json): OAuth2/OIDC authority · `docker/realm-export.json`

### Domain Services

- [Driver Service](https://github.com/xd-cods/cab-aggregator/blob/develop/driver-service/src/main/java/com/vlad/kuzhyr/driverservice/persistence/entity/Driver.java): driver and car domain · Owns drivers, cars, and driver busy state. · `driver-service/src/main/java/com/vlad/kuzhyr/driverservice/persistence/entity/Driver.java`
- [Passenger Service](https://github.com/xd-cods/cab-aggregator/blob/develop/passenger-service/src/main/java/com/vlad/kuzhyr/passengerservice/persistence/entity/Passenger.java): passenger domain · Owns passenger profiles. · `passenger-service/src/main/java/com/vlad/kuzhyr/passengerservice/persistence/entity/Passenger.java`
- [Ride Service](https://github.com/xd-cods/cab-aggregator/blob/develop/ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/RideServiceImpl.java): ride lifecycle orchestrator · Validates transitions and coordinates driver and passenger domains. · `ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/RideServiceImpl.java`
- **Ride Outbox**: transactional event staging · Durably stages ride changes before Kafka publication.
- **Rating Service**: rating domain · Persists ratings and local ride snapshots.

### Data & Operations

- [Mapbox](https://github.com/xd-cods/cab-aggregator/blob/develop/ride-service/src/main/java/com/vlad/kuzhyr/rideservice/utility/client/MapboxClient.java): geospatial API · `ride-service/src/main/java/com/vlad/kuzhyr/rideservice/utility/client/MapboxClient.java`
- [Redis](https://github.com/xd-cods/cab-aggregator/blob/develop/ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/cache/AddressCacheService.java): cache and geospatial store · Supports address caching and geospatial concerns. · `ride-service/src/main/java/com/vlad/kuzhyr/rideservice/service/impl/cache/AddressCacheService.java`
- **Kafka**: event stream
- **PostgreSQL Schemas**: isolated service databases · Passenger, driver, ride, and rating data are isolated by schema.
- [Docker Compose](https://github.com/xd-cods/cab-aggregator/blob/develop/docker/docker-compose.yml): local deployment · Defines the local platform deployment. · `docker/docker-compose.yml`
- **Observability Stack**: metrics logs traces · Prometheus, Grafana, Loki, Promtail, and Tempo assets.

## Connections

- Service Config → Config Server: served by
- Config Server → API Gateway: configuration
- Config Server → Auth Service: configuration
- Config Server → Driver Service: configuration
- Config Server → Passenger Service: configuration
- Config Server → Ride Service: configuration
- Config Server → Rating Service: configuration
- Eureka Server → API Gateway: service discovery
- Eureka Server → Auth Service: service discovery
- Eureka Server → Ride Service: service discovery
- API Gateway → Gateway Security: applies
- Gateway Security → Auth Service: routes authenticated requests
- Gateway Security → Driver Service: routes authenticated requests
- Gateway Security → Passenger Service: routes authenticated requests
- Gateway Security → Ride Service: routes authenticated requests
- Gateway Security → Rating Service: routes authenticated requests
- Auth Service → Keycloak: identity operations
- Auth Service → Driver Service: provisions driver profiles
- Auth Service → Passenger Service: provisions passenger profiles
- Ride Service → Driver Service: Feign driver coordination
- Ride Service → Passenger Service: Feign passenger coordination
- Ride Service → Mapbox: address and distance
- Ride Service → Redis: address cache
- Ride Service → Ride Outbox: stages ride events
- Ride Outbox → Kafka: scheduled publication
- Kafka → Driver Service: driver events
- Kafka → Passenger Service: passenger events
- Kafka → Rating Service: ride snapshots
- Driver Service → PostgreSQL Schemas: driver schema
- Passenger Service → PostgreSQL Schemas: passenger schema
- Ride Service → PostgreSQL Schemas: ride and outbox schema
- Rating Service → PostgreSQL Schemas: rating schema
- Docker Compose → Observability Stack: local stack assets