# abdullellahswe/fleetpulse architecture

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

- Interactive diagram: https://gitdiagram.com/abdullellahswe/fleetpulse
- Repository: https://github.com/abdullellahswe/fleetpulse

## Overview

FleetPulse is a fleet telemetry and operations dashboard for PHEV/GPS/OBD-II status, alerts, AI-assisted dispatch and analysis, LEZ geofencing, and fleet/ESG PDF reporting. Users sign in through Cognito, then use the dashboard to request fleet data and operational actions from the API; the API draws from PostgreSQL or fallback data and provides alert, AI, geospatial, and report capabilities. The repository also defines AWS infrastructure and a streaming ingestion path. Several frontend-to-API and streaming connections are inferred from the product structure rather than shown in the excerpts, so those links are dashed.

Main entry points: [`src/telemetry-api/main.py`](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/main.py) (Telemetry API), [`src/frontend/src/App.jsx`](https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/App.jsx) (Fleet dashboard), [`app.py`](https://github.com/abdullellahswe/fleetpulse/blob/main/app.py) (AWS deployment), [`src/telemetry-api/database.py`](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/database.py) (Fleet database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Dashboard"]
  node_dashboard["Fleet dashboard<br/>[App.jsx]"]
  node_login["Sign-in<br/>[Login.jsx]"]
  node_browser_auth["Browser auth<br/>[auth.js]"]
  node_map["Fleet map<br/>[FleetMap.jsx]"]
  node_alerts_panel["Alerts panel<br/>[AlertsPanel.jsx]"]
  node_assistant["Chat assistant<br/>[ChatAssistant.jsx]"]
  node_chat_message["Chat message<br/>[ChatMessage.jsx]"]
  node_engine_badge["AI status badge<br/>[EngineBadge.jsx]"]
end

subgraph group_api["Telemetry API"]
  node_api["Telemetry API<br/>[main.py]"]
  node_api_auth["Token verification<br/>[auth.py]"]
  node_ai["AI assistance<br/>[ai.py]"]
  node_alerts["Alert rules<br/>[alerts.py]"]
  node_geo["Geofencing<br/>[geo.py]"]
  node_report["PDF reporting<br/>[report.py]"]
end

subgraph group_data["Telemetry Data"]
  node_database["Fleet database access<br/>[database.py]"]
  node_fallback["Sample fleet data<br/>[fallback_data.py]"]
  node_producer["Telemetry producer"]
  node_consumer["Database consumer"]
end

subgraph group_cloud["AWS Platform"]
  node_aurora[("Aurora PostgreSQL<br/>[database_stack.py]")]
  node_streaming["Kinesis streaming<br/>[streaming_stack.py]"]
  node_cognito["Cognito<br/>[auth_stack.py]"]
  node_deployment["AWS deployment<br/>[app.py]"]
end

node_operator(("Fleet operator"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_login
node_login -->|"signs in"| node_browser_auth
node_browser_auth -->|"authenticates"| node_cognito
node_dashboard -->|"renders"| node_map
node_dashboard -->|"renders"| node_alerts_panel
node_dashboard -->|"renders"| node_assistant
node_assistant -->|"renders"| node_chat_message
node_chat_message -->|"renders"| node_engine_badge
node_dashboard -->|"renders"| node_engine_badge
node_dashboard -.->|"requests data"| node_api
node_api -->|"verifies requests"| node_api_auth
node_api_auth -->|"fetches signing keys"| node_cognito
node_api -->|"loads fleet"| node_database
node_api -->|"uses fallback"| node_fallback
node_api -->|"refreshes alerts"| node_alerts
node_alerts -->|"checks zones"| node_geo
node_api -->|"checks dispatch zone"| node_geo
node_api -->|"requests response"| node_ai
node_api -->|"builds PDF"| node_report
node_database -.->|"queries"| node_aurora
node_producer -.->|"publishes events"| node_streaming
node_streaming -.->|"delivers events"| node_consumer
node_consumer -.->|"writes telemetry"| node_database
node_deployment -->|"defines"| node_cognito
node_deployment -->|"defines"| node_aurora
node_deployment -->|"defines"| node_streaming

click node_dashboard "https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/App.jsx"
click node_login "https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/Login.jsx"
click node_browser_auth "https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/auth.js"
click node_map "https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/FleetMap.jsx"
click node_alerts_panel "https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/AlertsPanel.jsx"
click node_assistant "https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/ChatAssistant.jsx"
click node_chat_message "https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/ChatMessage.jsx"
click node_engine_badge "https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/EngineBadge.jsx"
click node_api "https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/main.py"
click node_api_auth "https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/auth.py"
click node_ai "https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/ai.py"
click node_alerts "https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/alerts.py"
click node_geo "https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/geo.py"
click node_report "https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/report.py"
click node_database "https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/database.py"
click node_fallback "https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/fallback_data.py"
click node_aurora "https://github.com/abdullellahswe/fleetpulse/blob/main/fleet_pulse/stacks/database_stack.py"
click node_streaming "https://github.com/abdullellahswe/fleetpulse/blob/main/fleet_pulse/stacks/streaming_stack.py"
click node_producer "https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/kinesis_producer.py"
click node_consumer "https://github.com/abdullellahswe/fleetpulse/blob/main/src/workers/kinesis_db_consumer.py"
click node_cognito "https://github.com/abdullellahswe/fleetpulse/blob/main/fleet_pulse/stacks/auth_stack.py"
click node_deployment "https://github.com/abdullellahswe/fleetpulse/blob/main/app.py"

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_dashboard,node_login,node_browser_auth,node_map,node_alerts_panel,node_assistant,node_chat_message,node_engine_badge toneBlue
class node_api,node_api_auth,node_ai,node_alerts,node_geo,node_report toneAmber
class node_database,node_fallback,node_producer,node_consumer toneMint
class node_aurora,node_streaming,node_cognito,node_deployment toneRose
class node_operator toneIndigo
```

## Components

### Dashboard

- [Fleet dashboard](https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/App.jsx): `src/frontend/src/App.jsx`
- [Sign-in](https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/Login.jsx): `src/frontend/src/Login.jsx`
- [Browser auth](https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/auth.js): `src/frontend/src/auth.js`
- [Fleet map](https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/FleetMap.jsx): `src/frontend/src/FleetMap.jsx`
- [Alerts panel](https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/AlertsPanel.jsx): `src/frontend/src/AlertsPanel.jsx`
- [Chat assistant](https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/ChatAssistant.jsx): `src/frontend/src/ChatAssistant.jsx`
- [Chat message](https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/ChatMessage.jsx): `src/frontend/src/ChatMessage.jsx`
- [AI status badge](https://github.com/abdullellahswe/fleetpulse/blob/main/src/frontend/src/EngineBadge.jsx): `src/frontend/src/EngineBadge.jsx`

### Telemetry API

- [Telemetry API](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/main.py): `src/telemetry-api/main.py`
- [Token verification](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/auth.py): `src/telemetry-api/auth.py`
- [AI assistance](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/ai.py): `src/telemetry-api/ai.py`
- [Alert rules](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/alerts.py): `src/telemetry-api/alerts.py`
- [Geofencing](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/geo.py): `src/telemetry-api/geo.py`
- [PDF reporting](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/report.py): `src/telemetry-api/report.py`

### Telemetry Data

- [Fleet database access](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/database.py): `src/telemetry-api/database.py`
- [Sample fleet data](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/fallback_data.py): `src/telemetry-api/fallback_data.py`
- [Telemetry producer](https://github.com/abdullellahswe/fleetpulse/blob/main/src/telemetry-api/kinesis_producer.py): `src/telemetry-api/kinesis_producer.py`
- [Database consumer](https://github.com/abdullellahswe/fleetpulse/blob/main/src/workers/kinesis_db_consumer.py): `src/workers/kinesis_db_consumer.py`

### AWS Platform

- [Aurora PostgreSQL](https://github.com/abdullellahswe/fleetpulse/blob/main/fleet_pulse/stacks/database_stack.py): `fleet_pulse/stacks/database_stack.py`
- [Kinesis streaming](https://github.com/abdullellahswe/fleetpulse/blob/main/fleet_pulse/stacks/streaming_stack.py): `fleet_pulse/stacks/streaming_stack.py`
- [Cognito](https://github.com/abdullellahswe/fleetpulse/blob/main/fleet_pulse/stacks/auth_stack.py): `fleet_pulse/stacks/auth_stack.py`
- [AWS deployment](https://github.com/abdullellahswe/fleetpulse/blob/main/app.py): `app.py`

### Other components

- **Fleet operator**

## Connections

- Fleet operator → Fleet dashboard: uses
- Fleet dashboard → Sign-in: renders (evidence: `src/frontend/src/App.jsx`)
- Sign-in → Browser auth: signs in (evidence: `src/frontend/src/Login.jsx`)
- Browser auth → Cognito: authenticates (evidence: `src/frontend/src/auth.js`)
- Fleet dashboard → Fleet map: renders (evidence: `src/frontend/src/App.jsx`)
- Fleet dashboard → Alerts panel: renders (evidence: `src/frontend/src/App.jsx`)
- Fleet dashboard → Chat assistant: renders (evidence: `src/frontend/src/App.jsx`)
- Chat assistant → Chat message: renders (evidence: `src/frontend/src/ChatAssistant.jsx`)
- Chat message → AI status badge: renders (evidence: `src/frontend/src/ChatMessage.jsx`)
- Fleet dashboard → AI status badge: renders (evidence: `src/frontend/src/App.jsx`)
- Fleet dashboard → Telemetry API: requests data
- Telemetry API → Token verification: verifies requests (evidence: `src/telemetry-api/main.py`)
- Token verification → Cognito: fetches signing keys (evidence: `src/telemetry-api/auth.py`)
- Telemetry API → Fleet database access: loads fleet (evidence: `src/telemetry-api/main.py`)
- Telemetry API → Sample fleet data: uses fallback (evidence: `src/telemetry-api/main.py`)
- Telemetry API → Alert rules: refreshes alerts (evidence: `src/telemetry-api/main.py`)
- Alert rules → Geofencing: checks zones (evidence: `src/telemetry-api/alerts.py`)
- Telemetry API → Geofencing: checks dispatch zone (evidence: `src/telemetry-api/main.py`)
- Telemetry API → AI assistance: requests response (evidence: `src/telemetry-api/main.py`)
- Telemetry API → PDF reporting: builds PDF (evidence: `src/telemetry-api/main.py`)
- Fleet database access → Aurora PostgreSQL: queries
- Telemetry producer → Kinesis streaming: publishes events
- Kinesis streaming → Database consumer: delivers events
- Database consumer → Fleet database access: writes telemetry
- AWS deployment → Cognito: defines (evidence: `app.py`)
- AWS deployment → Aurora PostgreSQL: defines (evidence: `app.py`)
- AWS deployment → Kinesis streaming: defines (evidence: `app.py`)
