Adamn32/zambia-smart-bus-tracker

Smart bus tracker system # Real-Time Transit Fleet Monitoring (Simulator + API + Dashboard) Containerized real-time GPS fleet tracking **simulation** for public transport minibuses in Lusaka. ## Simulation Notice This project is a **simulation/demo environment**. Vehicle telemetry is generated by the included simulator service (`gps-simulator`) and is not sourced from live production buses. ## Executive Summary This project demonstrates an end-to-end GPS fleet tracking simulation pipeline for Lusaka minibuses. Core flow: `Simulator -> API -> DB -> Frontend` ```mermaid flowchart LR SIM[GPS Simulator] -->|POST /location/update| API[FastAPI] API --> DB[(PostgreSQL + PostGIS)] API -->|WS /ws/locations| UI[React Dashboard] UI -->|GET /vehicles*| API ``` - `Simulator` (`gps-simulator`) generates mock GPS positions every 5 seconds - `API` (FastAPI) ingests telemetry, serves APIs, and streams updates via WebSockets - `DB` (PostgreSQL + PostGIS) persists location records - `Frontend` (React + Leaflet) visualizes live vehicles, route matching, and fleet stats - `Service Layer` (`backend/app/services/tracking_service.py`) isolates business logic for tracking and aggregation Why this matters for evaluators: - Shows real service-to-service integration in containers - Demonstrates backend ingest plus read-path for live dashboards - Represents a production-like architecture with controlled simulated data ## Overview This project runs four primary services with Docker Compose: - `postgres`: PostGIS-enabled PostgreSQL database - `api`: FastAPI backend for ingesting and serving simulated GPS locations - `simulator`: Python process that continuously posts mock vehicle locations - `dashboard`: React + Leaflet web UI There is also a `route-init` helper container in compose. With current backend code, it may exit after attempting `/routes` (see Known Limitations). ## Architecture - Backend: FastAPI + SQLAlchemy - Database: PostgreSQL 17 + PostGIS 3.4 - Frontend: React 18 + Leaflet - Orchestratio …