# aglili/delivery-ms architecture

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

- Interactive diagram: https://gitdiagram.com/aglili/delivery-ms
- Repository: https://github.com/aglili/delivery-ms

## Overview

##### Project Type and Purpose
- This is a standalone microservice (“Delivery Location Microservice”) built with FastAPI.
- Its purpose is to receive real-time location updates from delivery riders (via WebSocket), store and broadcast them, and expose REST endpoints to query rider status, active riders, nearby riders, and location history.
- It also includes a simulator to generate test traffic and a test script for user subscriptions.

##### File Structure
- Top level:
- Dockerfile & docker-compose.yml: containerize the service and Redis.
- requirements.txt: Python dependencies.
- src/main.py: entry point that spins up the FastAPI app.
- src/route.py: defines REST and WebSocket routes for rider updates.
- src/ws_subscribe.py: defines WebSocket routes for user subscriptions.
- src/utils/: helper modules
– location_store.py: Redis data access and logic.
– logger.py: logging utility.
– simulator.py: script that acts as many riders sending location updates.
– ws_subscriber_test.py: script that subscribes as a user and logs real-time updates.
- The presence of Docker files, Redis, and separate route modules indicates a microservice with both HTTP and WebSocket APIs, following a clear separation of concerns.

##### README for Additional Insights
- Confirms the use of:
- FastAPI for HTTP & WebSockets.
- Redis as a fast, persistent store (likely using pub/sub or hashes).
- Uvicorn as the ASGI server.
- A simulator for stress-testing.
- Describes the real-time flow: Rider → Backend → Redis store → Backend broadcasts → Users.

##### Main Components & Their Relationships
a. Components
- Rider clients (simulator or real devices)
- FastAPI service
– HTTP endpoints (route.py)
– WebSocket endpoints for riders (route.py)
– WebSocket endpoints for subscribers (ws_subscribe.py)
- Redis instance (for storage and possibly pub/sub)
- User clients (web or mobile apps subscribing via WebSocket)
- Simulator & test scripts (auxiliary)
b. Interactions / Data Flow
1. Rider WebSocket connection → FastAPI → location_store writes to Redis → FastAPI publishes to in-memory broadcast group → subscribers.
2. Subscriber WebSocket connection → FastAPI registers them in a subscriber list → on new updates, messages pushed to all subscribers.
3. HTTP clients → FastAPI REST endpoints → location_store reads from Redis → returns data.
c. Architectural Patterns
- Event-driven / Pub-Sub for real-time updates.
- Clear API layer separation: one module for rider ingestion, one for subscriber broadcast.
- Single microservice, but could scale horizontally behind a load balancer.
d. Key Technologies
- FastAPI (Python, Uvicorn)
- Redis (as a data store and pub/sub broker)
- Docker & Docker-Compose
- Python utilities (simulator, logger)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    RiderClients["Rider Clients"]:::external
    UserClients["User Subscribers"]:::external
    Simulator["Rider Simulator"]:::auxiliary
    SubscriberTest["Subscriber Test Script"]:::auxiliary

    %% Deployment Group
    subgraph "Docker Deployment" 
        direction TB
        DockerfileNode["Dockerfile"]:::auxiliary
        DockerComposeNode["docker-compose.yml"]:::auxiliary
        Requirements["requirements.txt"]:::auxiliary
    end

    %% Microservice Components
    subgraph "Delivery Location Microservice" 
        direction TB
        APIEntry["FastAPI App (src/main.py)"]:::service
        subgraph "HTTP & WebSocket API"
            direction TB
            RESTModule["REST Endpoints (src/route.py)"]:::service
            WSIngest["WebSocket Ingest (src/route.py)"]:::service
            WSSubscribe["WebSocket Subscribe (src/ws_subscribe.py)"]:::service
        end
        subgraph "Internal Utils"
            direction TB
            LocationStore["Location Store (src/utils/location_store.py)"]:::service
            Logger["Logger (src/utils/logger.py)"]:::service
        end
    end

    %% Data Store
    Redis["Redis Instance"]:::datastore

    %% Relationships
    RiderClients -->|"location updates"| WSIngest
    Simulator -->|"location updates"| WSIngest
    WSIngest -->|"store"| LocationStore
    LocationStore -->|"write/read"| Redis
    RESTModule -->|"HTTP GET"| LocationStore
    RESTModule -->|"HTTP GET Response"| UserClients
    WSIngest -->|"broadcast"| WSSubscribe
    SubscriberTest -->|"subscribe"| WSSubscribe
    WSSubscribe -->|"push updates"| UserClients

    %% Docker links
    DockerfileNode -.->|builds| APIEntry
    DockerComposeNode -.->|deploys| Redis

    %% Click Events
    click APIEntry "https://github.com/aglili/delivery-ms/blob/main/src/main.py"
    click RESTModule "https://github.com/aglili/delivery-ms/blob/main/src/route.py"
    click WSIngest "https://github.com/aglili/delivery-ms/blob/main/src/route.py"
    click WSSubscribe "https://github.com/aglili/delivery-ms/blob/main/src/ws_subscribe.py"
    click LocationStore "https://github.com/aglili/delivery-ms/blob/main/src/utils/location_store.py"
    click Logger "https://github.com/aglili/delivery-ms/blob/main/src/utils/logger.py"
    click Simulator "https://github.com/aglili/delivery-ms/blob/main/src/utils/simulator.py"
    click SubscriberTest "https://github.com/aglili/delivery-ms/blob/main/src/utils/ws_subscriber_test.py"
    click DockerfileNode "https://github.com/aglili/delivery-ms/tree/main/Dockerfile"
    click DockerComposeNode "https://github.com/aglili/delivery-ms/blob/main/docker-compose.yml"
    click Requirements "https://github.com/aglili/delivery-ms/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#E0F7FA,stroke:#006064,color:#006064
    classDef service fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef datastore fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef auxiliary fill:#F3E5F5,stroke:#4A148C,color:#4A148C
```
