# rahulkate173/fleetsync architecture

> Architecture diagram of the GitHub repository rahulkate173/fleetsync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahulkate173/fleetsync
- Repository: https://github.com/rahulkate173/fleetsync

## Overview

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: [`server/main.py`](https://github.com/rahulkate173/fleetsync/blob/main/server/main.py) (API server), [`src/App.jsx`](https://github.com/rahulkate173/fleetsync/blob/main/src/App.jsx) (App shell), [`src/pages/Dashboard/Dashboard.jsx`](https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Dashboard/Dashboard.jsx) (Admin dashboard), [`docker-compose.yml`](https://github.com/rahulkate173/fleetsync/blob/main/docker-compose.yml) (Compose stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_src_app["App shell<br/>react entry<br/>[App.jsx]"]
  node_src_home["Home<br/>landing page<br/>[Home.jsx]"]
  node_src_track["Track view<br/>shipment tracking<br/>[Track.jsx]"]
  node_src_driver["Driver console<br/>driver ui"]
  node_src_admin["Admin dashboard<br/>admin ui<br/>[Dashboard.jsx]"]
  node_src_analysis["Analysis<br/>analytics page<br/>[Analysis.jsx]"]
  node_src_settings["Settings<br/>preferences page<br/>[Settings.jsx]"]
  node_src_login["Logins<br/>auth pages<br/>[AdminLogin.jsx]"]
  node_ui_components["Shared UI<br/>components"]
  node_ui_context["Shared state<br/>react context"]
end

subgraph group_backend["Backend"]
  node_server_main["API server<br/>fastapi app<br/>[main.py]"]
  node_server_models["Data models<br/>schemas<br/>[models.py]"]
  node_server_db[("Database<br/>sqlite layer<br/>[database.py]")]
end

subgraph group_pipeline["Telemetry Pipeline"]
  node_kafka_producer["Kafka producer<br/>event publisher<br/>[producer.py]"]
  node_pathway_engine["Pathway engine<br/>stream processor<br/>[engine.py]"]
end

subgraph group_ops["Runtime"]
  node_frontend_backend_map["API map<br/>integration map"]
  node_compose["Compose stack<br/>orchestration<br/>[docker-compose.yml]"]
  node_run_script["Run script<br/>launcher<br/>[run.sh]"]
  node_docker_frontend["Frontend image<br/>container build"]
  node_docker_server["Server image<br/>container build<br/>[Dockerfile.server]"]
  node_docker_pathway["Pathway image<br/>container build<br/>[Dockerfile.pathway]"]
end

node_src_app -->|"routes to"| node_src_home
node_src_app -->|"routes to"| node_src_track
node_src_app -->|"routes to"| node_src_driver
node_src_app -->|"routes to"| node_src_admin
node_src_app -->|"routes to"| node_src_analysis
node_src_app -->|"routes to"| node_src_settings
node_src_app -->|"routes to"| node_src_login
node_src_track -->|"GET /track/{reference_id}"| node_server_main
node_src_driver -->|"POST /truck/gps"| node_server_main
node_src_driver -->|"GET /alerts/{truck_id}"| node_server_main
node_src_admin -->|"summary/ws"| node_server_main
node_src_admin -->|"uses"| node_ui_components
node_src_home -->|"uses"| node_ui_components
node_src_track -->|"reads state"| node_ui_context
node_src_admin -->|"reads state"| node_ui_context
node_server_main -->|"uses"| node_server_models
node_server_main -->|"stores in"| node_server_db
node_server_main -->|"POST /ingest/pathway"| node_pathway_engine
node_kafka_producer -->|"publishes to Kafka"| node_pathway_engine
node_pathway_engine -->|"forwards cleaned data"| node_server_main
node_server_main -.->|"event source"| node_kafka_producer
node_frontend_backend_map -.->|"documents"| node_src_app
node_frontend_backend_map -.->|"documents"| node_server_main
node_compose -->|"builds"| node_docker_frontend
node_compose -->|"builds"| node_docker_server
node_compose -->|"builds"| node_docker_pathway
node_run_script -->|"starts"| node_compose

click node_src_app "https://github.com/rahulkate173/fleetsync/blob/main/src/App.jsx"
click node_src_home "https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Home/Home.jsx"
click node_src_track "https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Track/Track.jsx"
click node_src_driver "https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Driver/DriverDashboard.jsx"
click node_src_admin "https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Dashboard/Dashboard.jsx"
click node_src_analysis "https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Analysis/Analysis.jsx"
click node_src_settings "https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Settingspage/Settings.jsx"
click node_src_login "https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Login/AdminLogin.jsx"
click node_ui_components "https://github.com/rahulkate173/fleetsync/tree/main/src/components"
click node_ui_context "https://github.com/rahulkate173/fleetsync/tree/main/src/context"
click node_server_main "https://github.com/rahulkate173/fleetsync/blob/main/server/main.py"
click node_server_models "https://github.com/rahulkate173/fleetsync/blob/main/server/models.py"
click node_server_db "https://github.com/rahulkate173/fleetsync/blob/main/server/database.py"
click node_kafka_producer "https://github.com/rahulkate173/fleetsync/blob/main/kafka/producer.py"
click node_pathway_engine "https://github.com/rahulkate173/fleetsync/blob/main/pathway/engine.py"
click node_frontend_backend_map "https://github.com/rahulkate173/fleetsync/blob/main/frontend-backend-mapping.md"
click node_compose "https://github.com/rahulkate173/fleetsync/blob/main/docker-compose.yml"
click node_run_script "https://github.com/rahulkate173/fleetsync/blob/main/run.sh"
click node_docker_frontend "https://github.com/rahulkate173/fleetsync/blob/main/Dockerfile.frontend"
click node_docker_server "https://github.com/rahulkate173/fleetsync/blob/main/Dockerfile.server"
click node_docker_pathway "https://github.com/rahulkate173/fleetsync/blob/main/Dockerfile.pathway"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_app,node_src_home,node_src_track,node_src_driver,node_src_admin,node_src_analysis,node_src_settings,node_src_login,node_ui_components,node_ui_context toneBlue
class node_server_main,node_server_models,node_server_db toneAmber
class node_kafka_producer,node_pathway_engine toneMint
class node_frontend_backend_map,node_compose,node_run_script,node_docker_frontend,node_docker_server,node_docker_pathway toneRose
```

## Components

### Frontend

React/Vite UI for users, drivers, and admins.

- [App shell](https://github.com/rahulkate173/fleetsync/blob/main/src/App.jsx): react entry · Top-level React application wiring routes and shared layout. · `src/App.jsx`
- [Home](https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Home/Home.jsx): landing page · Entry and navigation surface for the UI. · `src/pages/Home/Home.jsx`
- [Track view](https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Track/Track.jsx): shipment tracking · User-facing shipment status timeline and reference lookup. · `src/pages/Track/Track.jsx`
- [Driver console](https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Driver/DriverDashboard.jsx): driver ui · Driver-facing dashboard for location capture and alerts. · `src/pages/Driver/DriverDashboard.jsx`
- [Admin dashboard](https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Dashboard/Dashboard.jsx): admin ui · Fleet observability, analytics, and reporting workspace. · `src/pages/Dashboard/Dashboard.jsx`
- [Analysis](https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Analysis/Analysis.jsx): analytics page · Analytical views for fleet and shipment data. · `src/pages/Analysis/Analysis.jsx`
- [Settings](https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Settingspage/Settings.jsx): preferences page · Application and account configuration surface. · `src/pages/Settingspage/Settings.jsx`
- [Logins](https://github.com/rahulkate173/fleetsync/blob/main/src/pages/Login/AdminLogin.jsx): auth pages · Authentication entry points for admins, drivers, and users. · `src/pages/Login/AdminLogin.jsx`
- [Shared UI](https://github.com/rahulkate173/fleetsync/tree/main/src/components): components · Reusable visual and interaction components such as maps, charts, cards, PDF reports, and modals. · `src/components`
- [Shared state](https://github.com/rahulkate173/fleetsync/tree/main/src/context): react context · Theme, shipment, and fleet-state contexts shared across the UI. · `src/context`

### Backend

FastAPI service and persistence layer.

- [API server](https://github.com/rahulkate173/fleetsync/blob/main/server/main.py): fastapi app · HTTP and websocket API surface for shipments, dashboards, alerts, and ingestion. · `server/main.py`
- [Data models](https://github.com/rahulkate173/fleetsync/blob/main/server/models.py): schemas · Persistence and domain models for shipments, alerts, and fleet state. · `server/models.py`
- [Database](https://github.com/rahulkate173/fleetsync/blob/main/server/database.py): sqlite layer · Database setup and local SQLite-backed persistence. · `server/database.py`

### Telemetry Pipeline

Kafka-based ingestion and stream processing.

- [Kafka producer](https://github.com/rahulkate173/fleetsync/blob/main/kafka/producer.py): event publisher · Serializes telemetry and publishes live GPS events into Kafka. · `kafka/producer.py`
- [Pathway engine](https://github.com/rahulkate173/fleetsync/blob/main/pathway/engine.py): stream processor · Consumes Kafka events, filters bad telemetry, and forwards cleaned data. · `pathway/engine.py`

### Runtime

Build, deployment, and orchestration assets.

- [API map](https://github.com/rahulkate173/fleetsync/blob/main/frontend-backend-mapping.md): integration map · Documentation of frontend-to-backend route relationships. · `frontend-backend-mapping.md`
- [Compose stack](https://github.com/rahulkate173/fleetsync/blob/main/docker-compose.yml): orchestration · Local multi-service composition for frontend, backend, Kafka, and processing. · `docker-compose.yml`
- [Run script](https://github.com/rahulkate173/fleetsync/blob/main/run.sh): launcher · Convenience entry point for bringing up the full stack. · `run.sh`
- [Frontend image](https://github.com/rahulkate173/fleetsync/blob/main/Dockerfile.frontend): container build · Container build for the React/Vite frontend. · `Dockerfile.frontend`
- [Server image](https://github.com/rahulkate173/fleetsync/blob/main/Dockerfile.server): container build · Container build for the FastAPI backend. · `Dockerfile.server`
- [Pathway image](https://github.com/rahulkate173/fleetsync/blob/main/Dockerfile.pathway): container build · Container build for the stream-processing service. · `Dockerfile.pathway`

## Connections

- 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.
