xd-cods/cab-aggregator

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/.