# kshitijk4poor/logistics-platform architecture

> Architecture diagram of the GitHub repository kshitijk4poor/logistics-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kshitijk4poor/logistics-platform
- Repository: https://github.com/kshitijk4poor/logistics-platform

## Overview

##### Main Components

A. External Interfaces Layer:
- Nginx Load Balancer
- API Gateway (FastAPI)
- WebSocket Gateway

B. Core Services Layer:
- Booking Service
- Driver Service
- Tracking Service
- Pricing Service
- Analytics Service
- Admin Service
- Communication Service
- Assignment Service

C. Message Broker Layer:
- Apache Kafka (with multiple topics for different events)

D. Caching Layer:
- Redis Cache

E. Storage Layer:
- PostgreSQL Database
- PgBouncer Connection Pooler

F. Background Processing:
- Celery Workers
- Various Consumers (analytics, booking, demand, location)

**[Client Layer]**
- ↓
**[Gateway Layer]**
- ↓
**[Services Layer]**
- ↓
**[Message Broker Layer]**
- ↓
**[Data Layer]**

##### Key Relationships to Highlight

a. Data Flow Patterns:
- Real-time location updates: Driver → Tracking Service → Kafka → Location Consumer
- Booking Flow: API Gateway → Booking Service → Assignment Service → Driver Service
- Analytics Flow: Various Services → Kafka → Analytics Consumer → Analytics Service

b. Service Dependencies:
- How services communicate through Kafka
- Direct service-to-service communications
- Database access patterns

##### Implementation Details

**[Client Applications] → [Nginx Load Balancer]**
- ↓
**[FastAPI Gateway + WebSocket Gateway]**
- ↓
**[Service Mesh]**
- Booking Service ←→ Immediate/Scheduled Booking
- Driver Service ←→ Driver Availability
- Tracking Service ←→ Location Updates
- Pricing Service ←→ Dynamic Pricing
- Analytics Service ←→ Data Processing
- Admin Service ←→ Management Functions
- ↓
**[Apache Kafka Event Bus]**
- ↓
**[Consumers Layer]**
- ↓
**[Data Storage Layer]**
- PostgreSQL
- Redis Cache
- PgBouncer

##### Additional Elements

- Kubernetes deployment boundaries
- Security components (JWT, Rate Limiter)
- Monitoring points (Prometheus/Grafana)
- Circuit breakers and fallback paths

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        CL[Client Applications]
    end

    subgraph Gateway
        LB[Nginx Load Balancer]:::infra
        AG["API Gateway"]:::gateway
        WS["WebSocket Gateway"]:::gateway
    end

    subgraph Services
        BS["Booking Service"]:::service
        DS["Driver Service"]:::service
        TS["Tracking Service"]:::service
        PS["Pricing Service"]:::service
        AS["Analytics Service"]:::service
        ADS["Admin Service"]:::service
        CS["Communication Service"]:::service
        ASS["Assignment Service"]:::service
    end

    subgraph "Message Broker"
        KB["Apache Kafka"]:::broker
    end

    subgraph "Background Processing"
        AC["Analytics Consumer"]:::worker
        BC["Booking Consumer"]:::worker
        DC["Demand Consumer"]:::worker
        LC["Location Consumer"]:::worker
        CW["Celery Workers"]:::worker
    end

    subgraph "Data Layer"
        PG[(PostgreSQL)]:::database
        PGB[PgBouncer]:::database
        RD[(Redis Cache)]:::cache
    end

    %% Client Layer Connections
    CL --> LB
    LB --> AG
    LB --> WS

    %% Gateway to Services
    AG --> BS
    AG --> DS
    AG --> TS
    AG --> PS
    AG --> AS
    AG --> ADS
    WS --> CS

    %% Service Interconnections
    BS --> ASS
    ASS --> DS
    TS --> KB
    DS --> KB

    %% Message Broker to Consumers
    KB --> AC
    KB --> BC
    KB --> DC
    KB --> LC

    %% Consumers to Services
    AC --> AS
    BC --> BS
    LC --> TS

    %% Services to Data Layer
    BS --> PGB
    DS --> PGB
    TS --> PGB
    PS --> PGB
    AS --> PGB
    ADS --> PGB
    PGB --> PG

    %% Cache Connections
    BS --> RD
    DS --> RD
    TS --> RD
    PS --> RD

    %% Styles
    classDef service fill:#90EE90,stroke:#333,stroke-width:2px
    classDef gateway fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef broker fill:#FFA500,stroke:#333,stroke-width:2px
    classDef database fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef cache fill:#E6E6FA,stroke:#333,stroke-width:2px
    classDef worker fill:#FFD700,stroke:#333,stroke-width:2px
    classDef infra fill:#FF6B6B,stroke:#333,stroke-width:2px

    %% Click Events
    click LB "https://github.com/kshitijk4poor/logistics-platform/blob/main/nginx.conf"
    click AG "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/main.py"
    click WS "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/routes/websockets.py"
    click BS "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/booking/booking_service.py"
    click DS "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/drivers/driver_service.py"
    click TS "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/tracking/tracking_service.py"
    click PS "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/pricing/pricing_service.py"
    click AS "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/analytics/analytics_service.py"
    click ADS "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/admin/admin_service.py"
    click CS "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/communication/notification.py"
    click ASS "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/assignment/driver_assignment.py"
    click KB "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/messaging/kafka_service.py"
    click RD "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/caching/cache.py"
    click AC "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/analytics/analytics_consumer.py"
    click BC "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/booking/booking_consumer.py"
    click DC "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/demand/demand_consumer.py"
    click LC "https://github.com/kshitijk4poor/logistics-platform/blob/main/app/services/tracking/location_consumer.py"
    click PGB "https://github.com/kshitijk4poor/logistics-platform/blob/main/pgbouncer.ini"
    click PG "https://github.com/kshitijk4poor/logistics-platform/blob/main/db/database.py"
```
