How aryamang1/pullup works
1. Top-level shape
PullUp is split into three independently deployable Spring Boot microservices: RiderService, DriverService, and MatchingService. They do not share a database and do not call each other synchronously. Coordination happens through Kafka events, with Redis used only as a derived fast-lookup index.
2. RiderService boundary
RiderService owns the rider-side business flow: rider records, ride records, ride state transitions, and cancellation. Its domain includes Rider, Ride, RideStatus, CancelledBy, PaymentMethod, and geolocation/value objects. It exposes HTTP endpoints through RiderController, persists data through RiderRepository and RideRepository, and emits/consumes ride-related Kafka events.
3. DriverService boundary
DriverService owns driver lifecycle and availability. Its domain includes RideDriver, DriverLocation, DriverStatus, Vehicle, and VehicleStatus. It exposes driver-facing HTTP endpoints through DriverController, persists driver data through DriverRepository, and reacts to driver/location/status events from Kafka. It is also responsible for accepting or rejecting proposed assignments.
4. MatchingService boundary
MatchingService is intentionally stateless in business terms: it does not own a long-lived domain model. Its job is to receive ride requests, query nearby available drivers from Redis, and publish assignment proposals to Kafka. The core service class is DriverGeoQueryService, and the producer side is AssignmentKafkaService.
5. Primary event flow
The central workflow is: Ride requested → driver search → assignment proposed → driver decision → ride updated. RiderService publishes ride.requested; MatchingService consumes it, looks up nearby drivers in Redis, and publishes driver.assignment.proposed; DriverService consumes that proposal and emits either driver.assignment.accepted or driver.assignment.rejected; RiderService consumes acceptance to advance the ride state.
6. Redis as derived state
Redis is not the system of record. It holds a geospatial index of available drivers, effectively a performance cache for MatchingService. Driver location and availability changes are pushed into Redis by DriverService through event consumers and DriverGEOIndex. The Redis keyspace is centered on available drivers and GEO queries.
7. Kafka as the coordination backbone
Kafka is the only inter-service communication path. Each service has Kafka consumers/producers matching its responsibility:
- RiderService: ride request and assignment-acceptance consumption/production
- DriverService: assignment proposal, location update, and status-change consumption/production
- MatchingService: ride-request consumption and assignment-proposal production
The repository also includes explicit event classes per service, matching the JSON contract files in Ride-Event-Contracts.
8. Event contract governance
Ride-Event-Contracts contains versioned JSON schemas for ride, driver, and assignment events. This is the architectural contract boundary: services communicate through these event shapes rather than shared code. The repo’s README highlights that this avoids shared event modules and supports versioning and replay safety.
9. State machines and invariants
Both rides and drivers are modeled as explicit state machines rather than CRUD records. Ride states progress from REQUESTED to SEARCHING_DRIVER, ASSIGNED, IN_PROGRESS, and terminal states like COMPLETED or CANCELLED. Driver states move between OFFLINE, AVAILABLE, and BUSY. The domain classes deliberately avoid public setters so transitions happen through intent-based methods.
10. Persistence model
Each service owns its own persistence layer through Spring Data JPA repositories. RiderService persists riders and rides; DriverService persists drivers, vehicles, and driver-related state. MatchingService does not appear to own durable business data; its operational state is externalized to Redis and Kafka.
11. API layer vs event layer
The HTTP controllers are service-local entry points for creating riders, requesting rides, updating driver status, and similar actions. These APIs trigger local domain changes and event publication; they are not used for cross-service orchestration. That separation is a key diagram boundary: synchronous calls stay inside a service, while cross-service coordination is event-driven.
12. Operational dependencies
The concrete runtime stack is Java + Spring Boot, with Spring Kafka for event ingestion/publication, Spring Data Redis for GEO indexing, and Spring Data JPA for persistence. The README also indicates PostgreSQL as the durable database and Docker as the runtime/containerization layer. Observability and orchestration are future enhancements, not core architecture today.
13. Important architectural constraint
The system is intentionally eventually consistent. A ride may be requested before a suitable driver is indexed, and Redis may temporarily lag behind the source-of-truth database. That means a correct diagram should show asynchronous propagation and delayed convergence, not a single transactional request chain.
14. What to draw as the main subsystems
A faithful architecture diagram should show: RiderService, DriverService, MatchingService, Kafka topics/events between them, Redis as a derived driver availability index, and each service’s own database. The clearest arrows are: RiderService → Kafka → MatchingService → Kafka → DriverService → Kafka → RiderService, plus DriverService → Kafka/Redis for status and location updates.
Main entry points: DriverServiceImpl.java Driver Service · RiderFunctionImpl.java Rider Function · RideKafkaService.java Ride Kafka · DriverKafkaService.java Driver Kafka
Components 19
RiderService
Rider-side ride lifecycle, persistence, and Kafka integration.
- RiderController · Rider-facing entry point for rider and ride actions.
RiderService/src/main/java/com/PullUp/RiderService/web/RiderController.java - Rider Function · Implements rider business flow, ride creation, cancellation, and state transitions.
RiderService/src/main/java/com/PullUp/RiderService/service/RiderFunctionImpl.java - Ride Model · Rider, Ride, RideStatus, cancellation, payment, and geo value objects.
RiderService/src/main/java/com/PullUp/RiderService/model/Ride.java - Rider Repos · Persistence boundary for riders and rides.
RiderService/src/main/java/com/PullUp/RiderService/repository/RiderRepository.java - Ride Kafka · Publishes ride requests and consumes assignment acceptance events.
RiderService/src/main/java/com/PullUp/RiderService/kafkaservice/RideKafkaService.java - Rider DB · System of record for rider and ride state.
DriverService
Driver lifecycle, availability, persistence, and Kafka/Redis integration.
- DriverController · Driver-facing entry point for driver lifecycle and status changes.
DriverService/src/main/java/com/PullUp/DriverService/web/DriverController.java - Driver Service · Implements driver lifecycle, availability, and assignment decisions.
DriverService/src/main/java/com/PullUp/DriverService/service/DriverServiceImpl.java - Driver Model · RideDriver, DriverLocation, DriverStatus, Vehicle, and VehicleStatus.
DriverService/src/main/java/com/PullUp/DriverService/model/RideDriver.java - Driver Repo · Persistence boundary for drivers and related state.
DriverService/src/main/java/com/PullUp/DriverService/repository/DriverRepository.java - Driver Kafka · Consumes assignment proposals and location/status events; publishes driver decisions.
DriverService/src/main/java/com/PullUp/DriverService/kafkaservice/DriverKafkaService.java - GEO Index · Maintains derived driver availability and geospatial lookup state.
DriverService/src/main/java/com/PullUp/DriverService/redisservice/DriverGEOIndex.java - Driver DB · System of record for drivers, vehicles, and status.
MatchingService
Stateless matching workflow and Redis-backed driver lookup.
- Ride Consumer · Consumes ride requested events to start matching.
MatchingService/src/main/java/com/PullUp/MatchingService/consumer/RideRequestedConsumer.java - Geo Query · Looks up nearby available drivers in Redis for a ride request.
MatchingService/src/main/java/com/PullUp/MatchingService/service/DriverGeoQueryService.java - Assignment Producer · Publishes proposed driver assignments.
MatchingService/src/main/java/com/PullUp/MatchingService/producer/AssignmentKafkaService.java
Event Contracts
Versioned JSON schemas for inter-service events.
- JSON Schemas · Versioned ride, driver, and assignment event schemas.
Ride-Event-Contracts
Shared Infra
Cross-service coordination and external state stores.
- Redis · Fast geospatial index of available drivers, not the system of record.
- Kafka · Asynchronous coordination backbone between services.
Connections 25
- RiderController → Rider Function: HTTP request · Creates riders, requests rides, and manages cancellations.
- Rider Function → Ride Model: uses · Applies ride and rider state transitions.
- Rider Function → Rider Repos: persists · Stores rider and ride records.
- Rider Repos → Rider DB: writes · Rider-side durable storage.
- Rider Function → Ride Kafka: publishes / consumes · Emits ride requested and consumes assignment accepted.
- Ride Kafka → Kafka: events · Uses Kafka as the coordination channel.
- Kafka → Ride Consumer: ride.requested · Delivers ride request events to matching.
- Ride Consumer → Geo Query: triggers · Starts driver search for a ride request.
- Geo Query → Redis: geo query · Reads nearby available drivers from the derived index.
- Geo Query → Assignment Producer: proposal · Produces assignment proposals after lookup.
- Assignment Producer → Kafka: driver.assignment.proposed · Publishes proposed assignment events.
- Kafka → Driver Kafka: assignment proposed · Delivers proposed assignments to DriverService.
- DriverController → Driver Service: HTTP request · Registers drivers, updates location, and changes availability.
- Driver Service → Driver Model: uses · Manages driver and vehicle state machines.
- Driver Service → Driver Repo: persists · Stores driver-side durable state.
- Driver Repo → Driver DB: writes · Driver-side durable storage.
- Driver Service → Driver Kafka: publishes / consumes · Consumes proposals and emits accept/reject, location, and status events.
- Driver Kafka → Kafka: events · Uses Kafka as the coordination channel.
- Driver Service → GEO Index: updates index · Pushes availability and location changes into Redis.
- GEO Index → Redis: geo writes · Maintains derived availability index for matching.
- Kafka → Ride Kafka: driver.assignment.accepted · Delivers acceptance back to RiderService.
- Ride Kafka → Rider Function: advance ride · Moves ride from searching to assigned and beyond.
- JSON Schemas → Ride Kafka: schema · Event shape governance for rider events.
- JSON Schemas → Driver Kafka: schema · Event shape governance for driver and assignment events.
- JSON Schemas → Assignment Producer: schema · Event shape governance for matching events.