How aglili/delivery-ms works
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)