# 23e46pratham-lab/ecu-monitoring architecture

> Architecture diagram of the GitHub repository 23e46pratham-lab/ecu-monitoring, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/23e46pratham-lab/ecu-monitoring
- Repository: https://github.com/23e46pratham-lab/ecu-monitoring

## Overview

1. **Overall shape**
   - This is a **single-page frontend application** built with **React + TypeScript + Vite**.
   - There is **no separate backend service in the repo**; the app talks directly to external services from the client.

2. **App bootstrap and composition**
   - `index.html`, `src/main.tsx`, and `src/App.tsx` form the runtime entry path.
   - `App.tsx` is the top-level composition layer that likely wires together the main screens/widgets: dashboard, gauges, health monitor, chat, and driver-aura visualization.

3. **Presentation layer**
   - `src/components/` contains the UI boundaries:
     - `Dashboard.tsx` for the main status overview
     - `Gauges.tsx` for metric visualization
     - `HealthMonitor.tsx` for vehicle/AI health status
     - `ChatInterface.tsx` for conversational interaction
     - `DriverAura.tsx` for driver-state or behavior visualization
   - These components appear to be the main consumer of computed data and service outputs.

4. **Domain/analytics logic**
   - `src/logic/` holds the app’s core non-UI computations:
     - `driverBehavior.ts` for driving pattern scoring or classification
     - `mileage.ts` for distance/usage calculations
     - `mlHealth.ts` for model- or health-related scoring
   - This is the main boundary where raw telemetry becomes higher-level insights shown in the UI.

5. **Vehicle/telemetry simulation**
   - `src/services/ecuSimulator.ts` suggests the app can generate or emulate **ECU-like vehicle data**.
   - That simulator is likely the source of the app’s operational signals, feeding the analytics logic and dashboard widgets without requiring a physical vehicle connection.

6. **AI integration**
   - `src/services/geminiService.ts` is the integration point for **Google Gemini**.
   - The README explicitly requires `GEMINI_API_KEY`, so the chat/assistant experience is powered directly from the frontend via this service.
   - This is a key external boundary: UI requests → Gemini service → model response → chat UI.

7. **Firebase boundary**
   - `src/firebase.ts` plus `firestore.rules` indicate **Firebase/Firestore** is used as a cloud data layer.
   - The repo includes Firebase config files (`firebase-applet-config.json`, `firebase-blueprint.json`), implying the app may persist or sync state/results through Firestore.
   - `firestore.rules` is the security boundary controlling what client-side writes/reads are allowed.

8. **Shared types and utilities**
   - `src/types.ts` centralizes the app’s data contracts, which likely connect the simulator, logic layer, and UI components.
   - `src/lib/utils.ts` provides shared helper behavior used across components or calculations.
   - These files reduce coupling between the UI and the telemetry/AI logic.

9. **Data flow through the app**
   - The typical flow is:
     - simulated or stored vehicle data originates from the ECU simulator or Firestore,
     - domain logic transforms it into mileage, behavior, and health metrics,
     - UI components render those metrics in dashboard/gauge/monitor views,
     - the chat interface sends prompts to Gemini and displays responses,
     - Firebase may persist or retrieve state depending on the feature.

10. **Runtime and deployment assumptions**
   - The app runs in the browser and is started locally with `npm run dev`.
   - `vite.config.ts` and `package-lock.json` indicate a standard Vite-based frontend build/development workflow.
   - `public/` is the static asset boundary for files served directly by the app.

11. **What to draw in an architecture diagram**
   - A clean diagram would show:
     - **React UI shell** at the center
     - **UI components** on one side
     - **Logic layer** between UI and data sources
     - **ECU simulator** as a local data source
     - **Gemini API** as an external AI service
     - **Firebase/Firestore** as a cloud persistence layer with rules as the security boundary
   - The main architectural distinction is between **presentation**, **pure computation**, and **external service integrations**.

Main entry points: [`src/App.tsx`](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/App.tsx) (App), [`src/types.ts`](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/types.ts) (types.ts), [`src/services/ecuSimulator.ts`](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/services/ecuSimulator.ts) (ECU Simulator), [`src/firebase.ts`](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/firebase.ts) (firebase.ts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_index_html["index.html<br/>entry shell<br/>[index.html]"]
  node_main_tsx["main.tsx<br/>react entry<br/>[main.tsx]"]
  node_app_tsx["App<br/>composition root<br/>[App.tsx]"]
  node_public_assets[("public<br/>static assets")]
end

subgraph group_ui["UI"]
  node_dashboard["Dashboard<br/>overview screen<br/>[Dashboard.tsx]"]
  node_gauges["Gauges<br/>metrics view<br/>[Gauges.tsx]"]
  node_health_monitor["Health Monitor<br/>status panel<br/>[HealthMonitor.tsx]"]
  node_chat_interface["Chat<br/>assistant UI<br/>[ChatInterface.tsx]"]
  node_driver_aura["Driver Aura<br/>behavior viz<br/>[DriverAura.tsx]"]
end

subgraph group_logic["Logic"]
  node_driver_behavior["driverBehavior<br/>scoring logic<br/>[driverBehavior.ts]"]
  node_mileage["mileage<br/>distance logic<br/>[mileage.ts]"]
  node_ml_health["mlHealth<br/>health scoring<br/>[mlHealth.ts]"]
end

subgraph group_services["Services"]
  node_ecu_simulator[("ECU Simulator<br/>telemetry source<br/>[ecuSimulator.ts]")]
  node_gemini_service["Gemini Service<br/>ai adapter<br/>[geminiService.ts]"]
end

subgraph group_cloud["Cloud"]
  node_firebase_ts["firebase.ts<br/>firebase client<br/>[firebase.ts]"]
  node_firestore_rules["firestore.rules<br/>security policy<br/>[firestore.rules]"]
end

subgraph group_shared["Shared"]
  node_types_ts["types.ts<br/>contracts<br/>[types.ts]"]
  node_utils_ts["utils.ts<br/>helpers<br/>[utils.ts]"]
end

node_index_html -->|"loads"| node_main_tsx
node_main_tsx -->|"mounts"| node_app_tsx
node_app_tsx -->|"composes"| node_dashboard
node_app_tsx -->|"composes"| node_gauges
node_app_tsx -->|"composes"| node_health_monitor
node_app_tsx -->|"composes"| node_chat_interface
node_app_tsx -->|"composes"| node_driver_aura
node_app_tsx -->|"consumes"| node_ecu_simulator
node_app_tsx -->|"syncs"| node_firebase_ts
node_app_tsx -->|"shares"| node_types_ts
node_dashboard -->|"renders"| node_mileage
node_dashboard -->|"renders"| node_ml_health
node_gauges -->|"visualizes"| node_mileage
node_health_monitor -->|"visualizes"| node_ml_health
node_driver_aura -->|"visualizes"| node_driver_behavior
node_driver_behavior -->|"uses"| node_types_ts
node_mileage -->|"uses"| node_types_ts
node_ml_health -->|"uses"| node_types_ts
node_ecu_simulator -->|"produces"| node_types_ts
node_ecu_simulator -->|"feeds"| node_driver_behavior
node_ecu_simulator -->|"feeds"| node_mileage
node_ecu_simulator -->|"feeds"| node_ml_health
node_chat_interface -->|"calls"| node_gemini_service
node_gemini_service -.->|"may persist"| node_firebase_ts
node_firebase_ts -->|"governed by"| node_firestore_rules
node_firebase_ts -->|"uses"| node_types_ts
node_utils_ts -.->|"supports"| node_app_tsx

click node_index_html "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/index.html"
click node_main_tsx "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/main.tsx"
click node_app_tsx "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/App.tsx"
click node_dashboard "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/Dashboard.tsx"
click node_gauges "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/Gauges.tsx"
click node_health_monitor "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/HealthMonitor.tsx"
click node_chat_interface "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/ChatInterface.tsx"
click node_driver_aura "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/DriverAura.tsx"
click node_driver_behavior "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/logic/driverBehavior.ts"
click node_mileage "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/logic/mileage.ts"
click node_ml_health "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/logic/mlHealth.ts"
click node_ecu_simulator "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/services/ecuSimulator.ts"
click node_gemini_service "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/services/geminiService.ts"
click node_firebase_ts "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/firebase.ts"
click node_firestore_rules "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/firestore.rules"
click node_types_ts "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/types.ts"
click node_utils_ts "https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/lib/utils.ts"
click node_public_assets "https://github.com/23e46pratham-lab/ecu-monitoring/tree/main/public"

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_index_html,node_main_tsx,node_app_tsx,node_public_assets toneBlue
class node_dashboard,node_gauges,node_health_monitor,node_chat_interface,node_driver_aura toneAmber
class node_driver_behavior,node_mileage,node_ml_health toneMint
class node_ecu_simulator,node_gemini_service toneRose
class node_firebase_ts,node_firestore_rules toneIndigo
class node_types_ts,node_utils_ts toneTeal
```

## Components

### Bootstrap

Browser entry and application root

- [index.html](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/index.html): entry shell · Browser document that loads the app · `index.html`
- [main.tsx](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/main.tsx): react entry · Bootstraps the React application · `src/main.tsx`
- [App](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/App.tsx): composition root · Top-level UI composition and wiring · `src/App.tsx`
- [public](https://github.com/23e46pratham-lab/ecu-monitoring/tree/main/public): static assets · Static files served directly by Vite · `public`

### UI

Presentation components and screens

- [Dashboard](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/Dashboard.tsx): overview screen · Main status and summary view · `src/components/Dashboard.tsx`
- [Gauges](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/Gauges.tsx): metrics view · Metric and gauge visualization · `src/components/Gauges.tsx`
- [Health Monitor](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/HealthMonitor.tsx): status panel · Vehicle and AI health display · `src/components/HealthMonitor.tsx`
- [Chat](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/ChatInterface.tsx): assistant UI · Conversational interaction surface · `src/components/ChatInterface.tsx`
- [Driver Aura](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/components/DriverAura.tsx): behavior viz · Driver-state or behavior visualization · `src/components/DriverAura.tsx`

### Logic

Domain calculations and derived insights

- [driverBehavior](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/logic/driverBehavior.ts): scoring logic · Driving pattern analysis and classification · `src/logic/driverBehavior.ts`
- [mileage](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/logic/mileage.ts): distance logic · Distance and usage calculations · `src/logic/mileage.ts`
- [mlHealth](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/logic/mlHealth.ts): health scoring · Model or health-related scoring · `src/logic/mlHealth.ts`

### Services

Local simulators and external API adapters

- [ECU Simulator](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/services/ecuSimulator.ts): telemetry source · Generates or emulates vehicle signals · `src/services/ecuSimulator.ts`
- [Gemini Service](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/services/geminiService.ts): ai adapter · Frontend integration for Gemini requests · `src/services/geminiService.ts`

### Cloud

Firebase and Firestore boundary

- [firebase.ts](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/firebase.ts): firebase client · Firebase client setup and access layer · `src/firebase.ts`
- [firestore.rules](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/firestore.rules): security policy · Firestore read/write access rules · `firestore.rules`

### Shared

Cross-cutting types and utilities

- [types.ts](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/types.ts): contracts · Shared application data contracts · `src/types.ts`
- [utils.ts](https://github.com/23e46pratham-lab/ecu-monitoring/blob/main/src/lib/utils.ts): helpers · Shared utility functions · `src/lib/utils.ts`

## Connections

- index.html → main.tsx: loads · Browser document loads the React entry
- main.tsx → App: mounts · React mounts the application root
- App → Dashboard: composes · Top-level screen composition
- App → Gauges: composes · Renders metric widgets
- App → Health Monitor: composes · Renders health status view
- App → Chat: composes · Renders assistant chat UI
- App → Driver Aura: composes · Renders driver-state visualization
- App → ECU Simulator: consumes · Uses simulated telemetry as an input source
- App → firebase.ts: syncs · Connects to Firebase-backed state or data
- App → types.ts: shares · Uses shared contracts across features
- Dashboard → mileage: renders · Displays usage and distance derived metrics
- Dashboard → mlHealth: renders · Displays health-derived insights
- Gauges → mileage: visualizes · Turns computed metrics into gauges
- Health Monitor → mlHealth: visualizes · Shows health scoring and diagnostics
- Driver Aura → driverBehavior: visualizes · Shows behavior scoring and classification
- driverBehavior → types.ts: uses · Relies on shared telemetry and result shapes
- mileage → types.ts: uses · Uses shared measurement contracts
- mlHealth → types.ts: uses · Uses shared health data contracts
- ECU Simulator → types.ts: produces · Emits telemetry-shaped app data
- ECU Simulator → driverBehavior: feeds · Supplies inputs for behavioral analysis
- ECU Simulator → mileage: feeds · Supplies inputs for usage calculations
- ECU Simulator → mlHealth: feeds · Supplies inputs for health scoring
- Chat → Gemini Service: calls · Sends prompts to the AI adapter
- Gemini Service → firebase.ts: may persist · Can coordinate with app data or stored state
- firebase.ts → firestore.rules: governed by · Firestore access is constrained by rules
- firebase.ts → types.ts: uses · Firebase-bound data is typed through shared contracts
- utils.ts → App: supports · Shared helper behavior used across the app
