VeloCity is a containerized microservices application designed to simulate, ingest, process, and analyze real-time geospatial IoT telemetry. Built as a comprehensive Data Engineering portfolio project, it bridges the gap between raw sensor data, stream processing, and Generative AI.
- 📡 High-Throughput Data Streaming (IoT): A Python-based virtual sensor publishes GPS coordinates via the MQTT protocol (Eclipse Mosquitto broker), replacing traditional, blocking HTTP requests.
- 🧮 Real-Time Stream Processing: The FastAPI backend acts as a subscriber, intercepting the stream and applying the Haversine formula (spherical trigonometry) to calculate the truck's distance from a central hub dynamically.
- 🚨 Automated Geofencing: If a vehicle breaches a predefined 2km radius, the system instantly triggers a state update, turning the React dashboard's geofence red and throwing a critical alert.
- 🗺️ Intelligent Map Tracking: Features a premium Dark Mode SaaS UI with an auto-following map camera that automatically breaks its lock if the user manually drags the map to inspect the route.
- 🧠 GenAI Dispatcher: Integrates the modern
google-genaiSDK with Gemini 2.5 Flash. The AI acts as a virtual fleet manager, querying the PostGIS database to generate human-readable performance reports based on coordinate history. - 🐳 True Microservices Architecture: The entire stack (Database, Broker, Backend, Frontend, and Simulator) is orchestrated via Docker Compose across a custom Docker network.
- Virtual Truck (Python): Generates GPS drift and publishes to
velocity/telemetry. - Mosquitto Broker: Handles Pub/Sub message queuing.
- FastAPI Backend: Subscribes to the broker, runs math models, saves to DB, and serves REST endpoints.
- PostgreSQL + PostGIS: Stores the historical spatial data.
- React + Leaflet (Vite): Polls the backend, renders the live map, draws polyline paths, and displays the Gemini AI analysis.
- Frontend: React, Vite, React-Leaflet, Custom CSS (Dark Theme)
- Backend: Python 3.10, FastAPI, Uvicorn, Paho-MQTT, Google GenAI SDK
- Database: PostgreSQL with PostGIS extension, SQLModel (ORM)
- Infrastructure: Docker, Docker Compose, Eclipse Mosquitto
Because this project is fully containerized, you do not need to install Node.js, Python, or PostgreSQL on your local machine. You only need Docker.
1. Clone the repository:
git clone [https://github.com/YOUR_USERNAME/velocity.git](https://github.com/YOUR_USERNAME/velocity.git)
cd velocity2. Configure Environment Variables (Security First): This project uses a .env file to keep API keys secure.
Copy the example file:
cp .env.example .envOpen the new .env file and insert your free Google Gemini API key (get one from Google AI Studio),or use another API key from a different LLM.
3. Build and launch the cluster:
docker compose up --build4. Access the Dashboard:
Open your browser and navigate to http://localhost:5173. You will see the truck begin its route, update the KPI metrics in real-time, and eventually trigger the geofence breach.
While the current architecture successfully handles real-time single-vehicle telemetry, the following upgrades are planned for enterprise scale:
- True WebSockets: Replace the frontend's REST API polling (
setInterval) with a bi-directional WebSocket connection (FastAPI WebSockets) for instant, zero-latency state updates. - Multi-Vehicle Scaling: Upgrade the Python simulator to spawn multiple asynchronous threads, publishing telemetry for an entire fleet of 50+ trucks to distinct MQTT topics (e.g.,
velocity/telemetry/+). - Time-Series Database: Migrate from standard PostgreSQL to TimescaleDB or InfluxDB to optimize querying massive amounts of historical coordinate data.
- Cloud Deployment: Map the local Docker Compose network to a cloud provider (AWS EC2 or Google Cloud Compute Engine) with a reverse proxy (Nginx/Traefik) handling SSL termination.
This project is open-source and available under the MIT License.