How rahulkate173/fleetsync works
1. Overall shape
- This repo is a multi-service fleet visibility system, not a single app.
- The core runtime pieces are:
- React/Vite frontend
- FastAPI backend
- Kafka broker
- Pathway stream processor
- The architecture is centered on ingesting live truck telemetry, normalizing/analyzing it, and exposing it to admin, driver, and user-facing views.
2. Frontend boundary
- src/ is a single React application built with Vite.
- It contains separate page groups for distinct roles: Home, User tracking, Driver console, Admin dashboard, Analysis, Settings, and Login flows.
- Shared UI lives in src/components/ and shared state is split into contexts for theme, shipment data, and fleet stats.
- This frontend is the presentation layer; it consumes backend APIs and websocket updates but does not own the business state.
3. User shipment tracking flow
- The user-facing tracking path is built around reference ID lookup.
- The backend exposes GET /track/{reference_id} to return shipment state, represented in the README as a 4-stage timeline: departed → middle → loc → delivered.
- The Track and user pages render this as a status view, so the data flow here is simple request/response from frontend to FastAPI.
4. Driver telemetry ingestion flow
- The driver flow begins in the browser-based driver UI, which captures GPS location and vehicle metadata.
- Telemetry is sent to the backend via POST /truck/gps.
- From there, the system’s event pipeline pushes this data into Kafka as JSON, making Kafka the asynchronous buffer between live GPS capture and downstream processing.
5. Stream processing boundary
- pathway/engine.py is the stream-processing layer.
- It consumes Kafka events, filters invalid coordinates such as (0,0), and applies anomaly handling before forwarding processed data to the server through POST /ingest/pathway.
- This is the main trust boundary in the system: raw telemetry enters on one side, cleaned/derived events exit on the other.
6. Backend responsibilities
- server/main.py, models.py, and database.py define the FastAPI service and its persistence layer.
- The backend owns:
- shipment state
- live vehicle position ingestion
- dashboard summary data
- alert storage/delivery
- websocket fan-out for live map updates
- PDF report generation
- A local SQLite database file is present (server/fleetsync.db), with environment support for external database services such as Supabase/PostgreSQL.
7. Admin dashboard path
- The admin experience is built around live fleet observability.
- GET /dashboard/summary supports aggregate metrics, while WS /dashboard/map/ws streams live vehicle positions to the UI.
- Components like MultiVehicleMap, Chart, Card, ReportPDF, and AiModal indicate a dashboard that combines geospatial visualization, analytics, and reporting rather than simple CRUD screens.
8. Alerting loop
- Alerts are a separate feedback channel from telemetry ingestion.
- The admin can send alerts with POST /alerts/send, and the driver retrieves them with GET /alerts/{truck_id}.
- The driver UI includes sound-based notifications, so alerts are designed to be operational and immediate, not just logged.
9. Optional routing / ETA integrations
- The repository includes testing and environment hooks for routing providers such as Google Maps, TomTom, OpenRouteService, and OSRM.
- These are likely used for ETA prediction and route deviation checks, which aligns with the repo’s focus on delivery visibility and anomaly detection.
- They are optional external dependencies rather than the core transport pipeline.
10. Deployment and runtime packaging
- Each major service has its own Dockerfile: Dockerfile.frontend, Dockerfile.server, and Dockerfile.pathway.
- docker-compose.yml and run.sh support local orchestration of the full stack.
- nginx.conf suggests the frontend is intended to be served behind Nginx in production, while Railway deployment is documented as separate services for frontend, backend, and pathway processing.
Main entry points: main.py API server · App.jsx App shell · Dashboard.jsx Admin dashboard · docker-compose.yml Compose stack
Components 21
Frontend
React/Vite UI for users, drivers, and admins.
- App shell · Top-level React application wiring routes and shared layout.
src/App.jsx - Home · Entry and navigation surface for the UI.
src/pages/Home/Home.jsx - Track view · User-facing shipment status timeline and reference lookup.
src/pages/Track/Track.jsx - Driver console · Driver-facing dashboard for location capture and alerts.
src/pages/Driver/DriverDashboard.jsx - Admin dashboard · Fleet observability, analytics, and reporting workspace.
src/pages/Dashboard/Dashboard.jsx - Analysis · Analytical views for fleet and shipment data.
src/pages/Analysis/Analysis.jsx - Settings · Application and account configuration surface.
src/pages/Settingspage/Settings.jsx - Logins · Authentication entry points for admins, drivers, and users.
src/pages/Login/AdminLogin.jsx - Shared UI · Reusable visual and interaction components such as maps, charts, cards, PDF reports, and modals.
src/components - Shared state · Theme, shipment, and fleet-state contexts shared across the UI.
src/context
Backend
FastAPI service and persistence layer.
- API server · HTTP and websocket API surface for shipments, dashboards, alerts, and ingestion.
server/main.py - Data models · Persistence and domain models for shipments, alerts, and fleet state.
server/models.py - Database · Database setup and local SQLite-backed persistence.
server/database.py
Telemetry Pipeline
Kafka-based ingestion and stream processing.
- Kafka producer · Serializes telemetry and publishes live GPS events into Kafka.
kafka/producer.py - Pathway engine · Consumes Kafka events, filters bad telemetry, and forwards cleaned data.
pathway/engine.py
Runtime
Build, deployment, and orchestration assets.
- API map · Documentation of frontend-to-backend route relationships.
frontend-backend-mapping.md - Compose stack · Local multi-service composition for frontend, backend, Kafka, and processing.
docker-compose.yml - Run script · Convenience entry point for bringing up the full stack.
run.sh - Frontend image · Container build for the React/Vite frontend.
Dockerfile.frontend - Server image · Container build for the FastAPI backend.
Dockerfile.server - Pathway image · Container build for the stream-processing service.
Dockerfile.pathway
Connections 27
- App shell → Home: routes to · Main application shell renders the landing flow.
- App shell → Track view: routes to · Application exposes shipment tracking pages.
- App shell → Driver console: routes to · Application exposes driver-facing workflows.
- App shell → Admin dashboard: routes to · Application exposes admin dashboard views.
- App shell → Analysis: routes to · Application exposes analytics pages.
- App shell → Settings: routes to · Application exposes settings pages.
- App shell → Logins: routes to · Application exposes login flows.
- Track view → API server: GET /track/{reference_id} · User tracking view requests shipment status from the API.
- Driver console → API server: POST /truck/gps · Driver console submits live GPS telemetry.
- Driver console → API server: GET /alerts/{truck_id} · Driver console polls for operational alerts.
- Admin dashboard → API server: summary/ws · Dashboard consumes aggregate metrics and live map updates.
- Admin dashboard → Shared UI: uses · Dashboard composes maps, charts, cards, reports, and AI modal UI.
- Home → Shared UI: uses · Shared presentation pieces support the landing experience.
- Track view → Shared state: reads state · Tracking UI consumes shared shipment state.
- Admin dashboard → Shared state: reads state · Dashboard consumes shared fleet state and theme context.
- API server → Data models: uses · API server persists and serves domain entities.
- API server → Database: stores in · API server writes to the persistence layer.
- API server → Pathway engine: POST /ingest/pathway · Processed telemetry is accepted back into the API.
- Kafka producer → Pathway engine: publishes to Kafka · Telemetry events flow through Kafka into stream processing.
- Pathway engine → API server: forwards cleaned data · Stream processor sends normalized events to the backend.
- API server → Kafka producer: event source · Backend-side telemetry ingestion is the producer input for Kafka publishing.
- API map → App shell: documents · Maps UI routes and components to backend endpoints.
- API map → API server: documents · Captures the HTTP API contract.
- Compose stack → Frontend image: builds · Compose includes the frontend service image.
- Compose stack → Server image: builds · Compose includes the backend service image.
- Compose stack → Pathway image: builds · Compose includes the stream-processing service image.
- Run script → Compose stack: starts · Launch script orchestrates the composed stack.