# anupam2741/event-driven-logistics-engine architecture

> Architecture diagram of the GitHub repository anupam2741/event-driven-logistics-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anupam2741/event-driven-logistics-engine
- Repository: https://github.com/anupam2741/event-driven-logistics-engine

## Overview

This is an event-driven logistics platform for placing and tracking deliveries, dispatching riders, and ingesting live GPS updates. The main workflow starts with an order API request, checks rider availability over gRPC, persists and publishes the order, assigns a rider in the tracking service, and relays simulator pings and status changes back to the order service. The README documents cross-service behavior; source excerpts show key controller, assignment, and consumer calls. Some internals are unsampled, so their links are omitted or marked unverified.

Main entry points: [`order-service/src/main/java/com/project/service/OrderServiceImpl.java`](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/service/OrderServiceImpl.java) (Order lifecycle), [`tracking-service/src/main/java/com/project/service/RiderAssignmentService.java`](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/service/RiderAssignmentService.java) (Rider assignment), [`tracking-service/src/main/java/com/project/controller/LocationIngestionController.java`](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/controller/LocationIngestionController.java) (Location ingestion), [`order-service/src/main/java/com/project/service/OrderSafetyNetService.java`](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/service/OrderSafetyNetService.java) (Availability client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orders["Order lifecycle"]
  node_order_api["Order API"]
  node_order_logic["Order lifecycle"]
  node_availability_client["Availability client"]
  node_tracking_client["Tracking client"]
  node_order_store[("Order persistence")]
  node_pending_release[("Release retry state")]
  node_order_status_consumer["Order status consumer"]
end

subgraph group_dispatch["Rider dispatch"]
  node_tracking_service["Rider discovery RPC"]
  node_order_consumer["Order event consumer"]
  node_assignment["Rider assignment"]
  node_rider_db[("Rider records")]
  node_rider_bootstrap["Rider seeding"]
  node_rider_api["Rider administration"]
end

subgraph group_tracking["Live tracking"]
  node_location_api["Location ingestion"]
  node_navigation["Mission broadcast"]
  node_simulator["Rider simulator<br/>[RiderSimulation.py]"]
end

subgraph group_shared["Shared events"]
  node_shared_events["Order and status DTOs"]
  node_proto["Rider discovery contract"]
  node_status_producer["Status event producer"]
end

node_customer(("Customer or API client"))
node_kafka["Apache Kafka"]
node_redis[("Redis geo and pub/sub")]
node_postgres[("PostgreSQL")]

node_customer -->|"submits requests"| node_order_api
node_order_api -->|"delegates to"| node_order_logic
node_order_logic -->|"checks availability"| node_availability_client
node_availability_client -->|"checks riders"| node_tracking_service
node_availability_client -->|"uses contract"| node_proto
node_order_logic -->|"reads and writes"| node_order_store
node_order_logic -->|"publishes orders"| node_kafka
node_order_logic -->|"creates events"| node_shared_events
node_order_logic -->|"requests tracking"| node_tracking_client
node_tracking_client -->|"fetches location"| node_tracking_service
node_order_logic -->|"queues failed releases"| node_pending_release
node_kafka -->|"delivers orders"| node_order_consumer
node_order_consumer -->|"assigns riders"| node_assignment
node_assignment -->|"claims rider"| node_rider_db
node_assignment -->|"moves geo entry"| node_redis
node_assignment -->|"broadcasts mission"| node_navigation
node_navigation -->|"publishes mission"| node_redis
node_assignment -->|"emits assignment status"| node_status_producer
node_status_producer -->|"publishes status"| node_kafka
node_rider_api -->|"seeds riders"| node_rider_bootstrap
node_rider_bootstrap -->|"resets and saves"| node_rider_db
node_rider_bootstrap -->|"seeds geo pool"| node_redis
node_simulator -->|"receives missions"| node_redis
node_simulator -->|"sends GPS pings"| node_location_api
node_location_api -->|"updates geo index"| node_redis
node_location_api -->|"emits status updates"| node_status_producer
node_location_api -->|"releases delivered rider"| node_assignment
node_kafka -->|"delivers statuses"| node_order_status_consumer
node_order_status_consumer -->|"updates order"| node_order_store
node_order_logic -->|"persists order"| node_postgres
node_assignment -->|"persists rider claim"| node_postgres

click node_order_api "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/restController/OrderController.java"
click node_order_logic "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/service/OrderServiceImpl.java"
click node_availability_client "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/service/OrderSafetyNetService.java"
click node_tracking_client "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/service/OrderTrackingClient.java"
click node_order_store "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/repository/OrderRepository.java"
click node_pending_release "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/repository/PendingRiderReleaseRepository.java"
click node_order_status_consumer "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/kafka/OrderUpdateConsumer.java"
click node_tracking_service "https://github.com/anupam2741/event-driven-logistics-engine/tree/master/tracking-service/src/main/java/com/project/service"
click node_order_consumer "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/kafka/OrderConsumerService.java"
click node_assignment "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/service/RiderAssignmentService.java"
click node_rider_db "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/repository/RiderRepository.java"
click node_rider_bootstrap "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/service/DataBootstrapService.java"
click node_rider_api "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/controller/RiderController.java"
click node_location_api "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/controller/LocationIngestionController.java"
click node_navigation "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/service/RiderNavigationService.java"
click node_simulator "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/RiderSimulation.py"
click node_shared_events "https://github.com/anupam2741/event-driven-logistics-engine/tree/master/common-lib/src/main/java/com/project/dto"
click node_proto "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/common-lib/src/main/proto/rider_availability.proto"
click node_status_producer "https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/kafka/OrderStatusProducer.java"

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_order_api,node_order_logic,node_availability_client,node_tracking_client,node_order_store,node_pending_release,node_order_status_consumer,node_customer toneBlue
class node_tracking_service,node_order_consumer,node_assignment,node_rider_db,node_rider_bootstrap,node_rider_api,node_redis,node_postgres toneAmber
class node_location_api,node_navigation,node_simulator toneMint
class node_shared_events,node_proto,node_status_producer toneRose
class node_kafka toneIndigo
```

## Components

### Order lifecycle

- [Order API](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/restController/OrderController.java): `order-service/src/main/java/com/project/restController/OrderController.java`
- [Order lifecycle](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/service/OrderServiceImpl.java): `order-service/src/main/java/com/project/service/OrderServiceImpl.java`
- [Availability client](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/service/OrderSafetyNetService.java): `order-service/src/main/java/com/project/service/OrderSafetyNetService.java`
- [Tracking client](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/service/OrderTrackingClient.java): `order-service/src/main/java/com/project/service/OrderTrackingClient.java`
- [Order persistence](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/repository/OrderRepository.java): `order-service/src/main/java/com/project/repository/OrderRepository.java`
- [Release retry state](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/repository/PendingRiderReleaseRepository.java): `order-service/src/main/java/com/project/repository/PendingRiderReleaseRepository.java`
- [Order status consumer](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/order-service/src/main/java/com/project/kafka/OrderUpdateConsumer.java): `order-service/src/main/java/com/project/kafka/OrderUpdateConsumer.java`

### Rider dispatch

- [Rider discovery RPC](https://github.com/anupam2741/event-driven-logistics-engine/tree/master/tracking-service/src/main/java/com/project/service): `tracking-service/src/main/java/com/project/service`
- [Order event consumer](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/kafka/OrderConsumerService.java): `tracking-service/src/main/java/com/project/kafka/OrderConsumerService.java`
- [Rider assignment](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/service/RiderAssignmentService.java): `tracking-service/src/main/java/com/project/service/RiderAssignmentService.java`
- [Rider records](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/repository/RiderRepository.java): `tracking-service/src/main/java/com/project/repository/RiderRepository.java`
- [Rider seeding](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/service/DataBootstrapService.java): `tracking-service/src/main/java/com/project/service/DataBootstrapService.java`
- [Rider administration](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/controller/RiderController.java): `tracking-service/src/main/java/com/project/controller/RiderController.java`

### Live tracking

- [Location ingestion](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/controller/LocationIngestionController.java): `tracking-service/src/main/java/com/project/controller/LocationIngestionController.java`
- [Mission broadcast](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/service/RiderNavigationService.java): `tracking-service/src/main/java/com/project/service/RiderNavigationService.java`
- [Rider simulator](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/RiderSimulation.py): `RiderSimulation.py`

### Shared events

- [Order and status DTOs](https://github.com/anupam2741/event-driven-logistics-engine/tree/master/common-lib/src/main/java/com/project/dto): `common-lib/src/main/java/com/project/dto`
- [Rider discovery contract](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/common-lib/src/main/proto/rider_availability.proto): `common-lib/src/main/proto/rider_availability.proto`
- [Status event producer](https://github.com/anupam2741/event-driven-logistics-engine/blob/master/tracking-service/src/main/java/com/project/kafka/OrderStatusProducer.java): `tracking-service/src/main/java/com/project/kafka/OrderStatusProducer.java`

### Other components

- **Customer or API client**
- **Apache Kafka**
- **Redis geo and pub/sub**
- **PostgreSQL**

## Connections

- Customer or API client → Order API: submits requests (evidence: `order-service/src/main/java/com/project/restController/OrderController.java`)
- Order API → Order lifecycle: delegates to (evidence: `order-service/src/main/java/com/project/restController/OrderController.java`)
- Order lifecycle → Availability client: checks availability (evidence: `order-service/src/main/java/com/project/service/OrderServiceImpl.java`)
- Availability client → Rider discovery RPC: checks riders
- Availability client → Rider discovery contract: uses contract
- Order lifecycle → Order persistence: reads and writes (evidence: `order-service/src/main/java/com/project/service/OrderServiceImpl.java`)
- Order lifecycle → Apache Kafka: publishes orders
- Order lifecycle → Order and status DTOs: creates events (evidence: `order-service/src/main/java/com/project/service/OrderServiceImpl.java`)
- Order lifecycle → Tracking client: requests tracking (evidence: `order-service/src/main/java/com/project/service/OrderServiceImpl.java`)
- Tracking client → Rider discovery RPC: fetches location
- Order lifecycle → Release retry state: queues failed releases (evidence: `order-service/src/main/java/com/project/service/OrderServiceImpl.java`)
- Apache Kafka → Order event consumer: delivers orders (evidence: `tracking-service/src/main/java/com/project/kafka/OrderConsumerService.java`)
- Order event consumer → Rider assignment: assigns riders (evidence: `tracking-service/src/main/java/com/project/kafka/OrderConsumerService.java`)
- Rider assignment → Rider records: claims rider (evidence: `tracking-service/src/main/java/com/project/service/RiderAssignmentService.java`)
- Rider assignment → Redis geo and pub/sub: moves geo entry (evidence: `tracking-service/src/main/java/com/project/service/RiderAssignmentService.java`)
- Rider assignment → Mission broadcast: broadcasts mission (evidence: `tracking-service/src/main/java/com/project/service/RiderAssignmentService.java`)
- Mission broadcast → Redis geo and pub/sub: publishes mission
- Rider assignment → Status event producer: emits assignment status (evidence: `tracking-service/src/main/java/com/project/service/RiderAssignmentService.java`)
- Status event producer → Apache Kafka: publishes status (evidence: `tracking-service/src/main/java/com/project/kafka/OrderStatusProducer.java`)
- Rider administration → Rider seeding: seeds riders (evidence: `tracking-service/src/main/java/com/project/controller/RiderController.java`)
- Rider seeding → Rider records: resets and saves (evidence: `tracking-service/src/main/java/com/project/service/DataBootstrapService.java`)
- Rider seeding → Redis geo and pub/sub: seeds geo pool (evidence: `tracking-service/src/main/java/com/project/service/DataBootstrapService.java`)
- Rider simulator → Redis geo and pub/sub: receives missions
- Rider simulator → Location ingestion: sends GPS pings
- Location ingestion → Redis geo and pub/sub: updates geo index (evidence: `tracking-service/src/main/java/com/project/controller/LocationIngestionController.java`)
- Location ingestion → Status event producer: emits status updates (evidence: `tracking-service/src/main/java/com/project/controller/LocationIngestionController.java`)
- Location ingestion → Rider assignment: releases delivered rider (evidence: `tracking-service/src/main/java/com/project/controller/LocationIngestionController.java`)
- Apache Kafka → Order status consumer: delivers statuses
- Order status consumer → Order persistence: updates order
- Order lifecycle → PostgreSQL: persists order
- Rider assignment → PostgreSQL: persists rider claim