# sergigarriga/car-stats-dashboard architecture

> Architecture diagram of the GitHub repository sergigarriga/car-stats-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sergigarriga/car-stats-dashboard
- Repository: https://github.com/sergigarriga/car-stats-dashboard

## Overview

##### Project type and purpose
- This is a single-page, full-stack (monolithic) Streamlit web application for analyzing PHEV driving data.
- Purpose: Load trip data from a CSV, perform cleaning/transformation, compute statistics and predictions (including AI-powered explanations), and render interactive visualizations.

##### File structure
- Top level:
- src/ – application code
– main.py: entry point (Streamlit app)
– components/menu.py: UI/sidebar/menu definitions
– utils/data_processing.py: data ingestion, cleaning, transformations
– utils/predictions.py: future projections logic
– utils/ai_caller.py: (in README) AI model integration
– assets/car_stats.csv: sample data
- tests/ – pytest unit tests for data_processing, predictions, AI calls
- requirements.txt, README.md, LICENSE, .gitignore

##### README for additional insights
- Confirms use of Streamlit for UI, Pandas/Numpy for data, Plotly for visualizations, and optionally an external AI service.
- Describes features: dashboards, filtering, cost/savings analysis, data explorer, AI-generated chart explanations.

##### Main components & their interactions
a. Presentation Layer
– Streamlit server (main.py)
– UI Components (menu.py)
– Plotly chart rendering
b. Business Logic Layer
– DataProcessing module
- load_data()
- clean and normalize columns
– Predictions module
- compute historical averages
- project next-month metrics
– AI Caller module
- format chart metadata
- invoke external AI model (e.g., OpenAI API)
c. Data Layer
– CSV file (assets/car_stats.csv)
– In-memory Pandas DataFrame
d. External Services
– AI model endpoint (optional)
e. Testing Layer
– pytest harness
– Mocked AI calls, unit tests on utils

##### Architectural patterns & design principles
- Layered architecture separating UI, business logic, and data access.
- Single-process, modular code organization (packages for components and utils).
- Dependency injection via function parameters for testability (e.g., enabling mock CSV inputs or AI responses).
- Interactive, event-driven flow driven by Streamlit reruns on user input.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend/UI"
        Browser["User (Web Browser)"]:::ui
        Streamlit["Streamlit App\n(main.py)"]:::ui
        UI["UI Components\n(menu.py + Plotly)"]:::ui
    end

    subgraph "Business Logic"
        DataProc["Data Processing Module\n(data_processing.py)"]:::logic
        Pred["Predictions Module\n(predictions.py)"]:::logic
        AI["AI Caller Module"]:::logic
    end

    subgraph "Data Layer"
        CSV[(CSV Data Store\ncar_stats.csv)]:::data
        DF["In-memory Pandas DataFrame"]:::data
    end

    subgraph "External Services"
        ExtAI["External AI Service"]:::external
    end

    subgraph "Testing"
        TS1["tests/test_data_processing.py"]:::tests
        TS2["tests/test_predictions.py"]:::tests
    end

    Browser -->|"HTTP/WebSocket"| Streamlit
    Streamlit -->|"build UI"| UI
    Streamlit -->|"load_data() returns DataFrame"| DataProc
    DataProc -->|"read CSV"| CSV
    DataProc -->|"return DataFrame"| DF
    Streamlit -->|"pass DataFrame"| Pred
    Pred -->|"return projections"| Streamlit
    Streamlit -->|"call AI (optional)"| AI
    AI -.->|"POST chart metadata"| ExtAI
    ExtAI -.->|"return explanation text"| AI
    AI -->|"explanation text"| Streamlit
    UI -->|"render charts"| Browser

    TS1 -->|"unit tests"| DataProc
    TS2 -->|"unit tests"| Pred

    click Streamlit "https://github.com/sergigarriga/car-stats-dashboard/blob/main/src/main.py"
    click UI "https://github.com/sergigarriga/car-stats-dashboard/blob/main/src/components/menu.py"
    click DataProc "https://github.com/sergigarriga/car-stats-dashboard/blob/main/src/utils/data_processing.py"
    click Pred "https://github.com/sergigarriga/car-stats-dashboard/blob/main/src/utils/predictions.py"
    click CSV "https://github.com/sergigarriga/car-stats-dashboard/blob/main/src/data/car_stats.csv"
    click TS1 "https://github.com/sergigarriga/car-stats-dashboard/blob/main/tests/test_data_processing.py"
    click TS2 "https://github.com/sergigarriga/car-stats-dashboard/blob/main/tests/test_predictions.py"

    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#F5DEB3,stroke:#333,stroke-width:1px
    classDef external fill:#FFD700,stroke:#333,stroke-width:1px
    classDef tests stroke-dasharray:5 5,fill:none,stroke:#000,stroke-width:1px
```
