# aryamang1/pullup architecture

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

- Interactive diagram: https://gitdiagram.com/aryamang1/pullup
- Repository: https://github.com/aryamang1/pullup

## Overview

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: [`DriverService/src/main/java/com/PullUp/DriverService/service/DriverServiceImpl.java`](https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/service/DriverServiceImpl.java) (Driver Service), [`RiderService/src/main/java/com/PullUp/RiderService/service/RiderFunctionImpl.java`](https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/service/RiderFunctionImpl.java) (Rider Function), [`RiderService/src/main/java/com/PullUp/RiderService/kafkaservice/RideKafkaService.java`](https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/kafkaservice/RideKafkaService.java) (Ride Kafka), [`DriverService/src/main/java/com/PullUp/DriverService/kafkaservice/DriverKafkaService.java`](https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/kafkaservice/DriverKafkaService.java) (Driver Kafka)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rider["RiderService"]
  node_rider_controller["RiderController<br/>HTTP API"]
  node_rider_service["Rider Function<br/>domain service"]
  node_rider_model["Ride Model<br/>domain model<br/>[Ride.java]"]
  node_rider_repos[("Rider Repos<br/>JPA repositories")]
  node_rider_kafka["Ride Kafka<br/>Kafka adapter"]
  node_rider_db[("Rider DB<br/>PostgreSQL")]
end

subgraph group_driver["DriverService"]
  node_driver_controller["DriverController<br/>HTTP API"]
  node_driver_service["Driver Service<br/>domain service"]
  node_driver_model["Driver Model<br/>domain model<br/>[RideDriver.java]"]
  node_driver_repo[("Driver Repo<br/>JPA repository")]
  node_driver_kafka["Driver Kafka<br/>Kafka adapter"]
  node_driver_geo_index["GEO Index<br/>Redis indexer"]
  node_driver_db[("Driver DB<br/>PostgreSQL")]
end

subgraph group_matching["MatchingService"]
  node_matching_consumer["Ride Consumer<br/>Kafka consumer"]
  node_matching_service["Geo Query<br/>matching service"]
  node_matching_producer["Assignment Producer<br/>Kafka producer"]
end

subgraph group_contracts["Event Contracts"]
  node_contracts["JSON Schemas<br/>event contracts"]
end

subgraph group_infra["Shared Infra"]
  node_redis[("Redis<br/>derived store")]
  node_kafka["Kafka<br/>event bus"]
end

node_rider_controller -->|"HTTP request"| node_rider_service
node_rider_service -->|"uses"| node_rider_model
node_rider_service -->|"persists"| node_rider_repos
node_rider_repos -->|"writes"| node_rider_db
node_rider_service -->|"publishes / consumes"| node_rider_kafka
node_rider_kafka -->|"events"| node_kafka
node_kafka -->|"ride.requested"| node_matching_consumer
node_matching_consumer -->|"triggers"| node_matching_service
node_matching_service -->|"geo query"| node_redis
node_matching_service -->|"proposal"| node_matching_producer
node_matching_producer -->|"driver.assignment.proposed"| node_kafka
node_kafka -->|"assignment proposed"| node_driver_kafka
node_driver_controller -->|"HTTP request"| node_driver_service
node_driver_service -->|"uses"| node_driver_model
node_driver_service -->|"persists"| node_driver_repo
node_driver_repo -->|"writes"| node_driver_db
node_driver_service -->|"publishes / consumes"| node_driver_kafka
node_driver_kafka -->|"events"| node_kafka
node_driver_service -->|"updates index"| node_driver_geo_index
node_driver_geo_index -->|"geo writes"| node_redis
node_kafka -->|"driver.assignment.accepted"| node_rider_kafka
node_rider_kafka -->|"advance ride"| node_rider_service
node_contracts -.->|"schema"| node_rider_kafka
node_contracts -.->|"schema"| node_driver_kafka
node_contracts -.->|"schema"| node_matching_producer

click node_rider_controller "https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/web/RiderController.java"
click node_rider_service "https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/service/RiderFunctionImpl.java"
click node_rider_model "https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/model/Ride.java"
click node_rider_repos "https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/repository/RiderRepository.java"
click node_rider_kafka "https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/kafkaservice/RideKafkaService.java"
click node_driver_controller "https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/web/DriverController.java"
click node_driver_service "https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/service/DriverServiceImpl.java"
click node_driver_model "https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/model/RideDriver.java"
click node_driver_repo "https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/repository/DriverRepository.java"
click node_driver_kafka "https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/kafkaservice/DriverKafkaService.java"
click node_driver_geo_index "https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/redisservice/DriverGEOIndex.java"
click node_matching_consumer "https://github.com/aryamang1/pullup/blob/main/MatchingService/src/main/java/com/PullUp/MatchingService/consumer/RideRequestedConsumer.java"
click node_matching_service "https://github.com/aryamang1/pullup/blob/main/MatchingService/src/main/java/com/PullUp/MatchingService/service/DriverGeoQueryService.java"
click node_matching_producer "https://github.com/aryamang1/pullup/blob/main/MatchingService/src/main/java/com/PullUp/MatchingService/producer/AssignmentKafkaService.java"
click node_contracts "https://github.com/aryamang1/pullup/tree/main/Ride-Event-Contracts"

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_rider_controller,node_rider_service,node_rider_model,node_rider_repos,node_rider_kafka,node_rider_db toneBlue
class node_driver_controller,node_driver_service,node_driver_model,node_driver_repo,node_driver_kafka,node_driver_geo_index,node_driver_db toneAmber
class node_matching_consumer,node_matching_service,node_matching_producer toneMint
class node_contracts toneRose
class node_redis,node_kafka toneIndigo
```

## Components

### RiderService

Rider-side ride lifecycle, persistence, and Kafka integration.

- [RiderController](https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/web/RiderController.java): HTTP API · Rider-facing entry point for rider and ride actions. · `RiderService/src/main/java/com/PullUp/RiderService/web/RiderController.java`
- [Rider Function](https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/service/RiderFunctionImpl.java): domain service · Implements rider business flow, ride creation, cancellation, and state transitions. · `RiderService/src/main/java/com/PullUp/RiderService/service/RiderFunctionImpl.java`
- [Ride Model](https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/model/Ride.java): domain model · Rider, Ride, RideStatus, cancellation, payment, and geo value objects. · `RiderService/src/main/java/com/PullUp/RiderService/model/Ride.java`
- [Rider Repos](https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/repository/RiderRepository.java): JPA repositories · Persistence boundary for riders and rides. · `RiderService/src/main/java/com/PullUp/RiderService/repository/RiderRepository.java`
- [Ride Kafka](https://github.com/aryamang1/pullup/blob/main/RiderService/src/main/java/com/PullUp/RiderService/kafkaservice/RideKafkaService.java): Kafka adapter · Publishes ride requests and consumes assignment acceptance events. · `RiderService/src/main/java/com/PullUp/RiderService/kafkaservice/RideKafkaService.java`
- **Rider DB**: PostgreSQL · System of record for rider and ride state.

### DriverService

Driver lifecycle, availability, persistence, and Kafka/Redis integration.

- [DriverController](https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/web/DriverController.java): HTTP API · Driver-facing entry point for driver lifecycle and status changes. · `DriverService/src/main/java/com/PullUp/DriverService/web/DriverController.java`
- [Driver Service](https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/service/DriverServiceImpl.java): domain service · Implements driver lifecycle, availability, and assignment decisions. · `DriverService/src/main/java/com/PullUp/DriverService/service/DriverServiceImpl.java`
- [Driver Model](https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/model/RideDriver.java): domain model · RideDriver, DriverLocation, DriverStatus, Vehicle, and VehicleStatus. · `DriverService/src/main/java/com/PullUp/DriverService/model/RideDriver.java`
- [Driver Repo](https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/repository/DriverRepository.java): JPA repository · Persistence boundary for drivers and related state. · `DriverService/src/main/java/com/PullUp/DriverService/repository/DriverRepository.java`
- [Driver Kafka](https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/kafkaservice/DriverKafkaService.java): Kafka adapter · Consumes assignment proposals and location/status events; publishes driver decisions. · `DriverService/src/main/java/com/PullUp/DriverService/kafkaservice/DriverKafkaService.java`
- [GEO Index](https://github.com/aryamang1/pullup/blob/main/DriverService/src/main/java/com/PullUp/DriverService/redisservice/DriverGEOIndex.java): Redis indexer · Maintains derived driver availability and geospatial lookup state. · `DriverService/src/main/java/com/PullUp/DriverService/redisservice/DriverGEOIndex.java`
- **Driver DB**: PostgreSQL · System of record for drivers, vehicles, and status.

### MatchingService

Stateless matching workflow and Redis-backed driver lookup.

- [Ride Consumer](https://github.com/aryamang1/pullup/blob/main/MatchingService/src/main/java/com/PullUp/MatchingService/consumer/RideRequestedConsumer.java): Kafka consumer · Consumes ride requested events to start matching. · `MatchingService/src/main/java/com/PullUp/MatchingService/consumer/RideRequestedConsumer.java`
- [Geo Query](https://github.com/aryamang1/pullup/blob/main/MatchingService/src/main/java/com/PullUp/MatchingService/service/DriverGeoQueryService.java): matching service · Looks up nearby available drivers in Redis for a ride request. · `MatchingService/src/main/java/com/PullUp/MatchingService/service/DriverGeoQueryService.java`
- [Assignment Producer](https://github.com/aryamang1/pullup/blob/main/MatchingService/src/main/java/com/PullUp/MatchingService/producer/AssignmentKafkaService.java): Kafka 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](https://github.com/aryamang1/pullup/tree/main/Ride-Event-Contracts): event contracts · Versioned ride, driver, and assignment event schemas. · `Ride-Event-Contracts`

### Shared Infra

Cross-service coordination and external state stores.

- **Redis**: derived store · Fast geospatial index of available drivers, not the system of record.
- **Kafka**: event bus · Asynchronous coordination backbone between services.

## Connections

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