# iamhuzaifasabahuddin/hexz_automations architecture

> Architecture diagram of the GitHub repository iamhuzaifasabahuddin/hexz_automations, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iamhuzaifasabahuddin/hexz_automations
- Repository: https://github.com/iamhuzaifasabahuddin/hexz_automations

## Overview

##### Project Type and Purpose
- This is a Python-based data-integration and reporting tool that combines a lightweight “frontend” (Streamlit dashboard), a backend integration layer (Notion API, Gmail SMTP), and a scheduled automation (GitHub Actions).
- Its purpose is to let you log, view, analyze, and automatically email monthly summaries of ride/commute data, all orchestrated via Python scripts.

##### Key Components in the File Tree
- Budget.py              → Likely the Streamlit app entrypoint for interactive charts and dashboards.
- Notion.py              → Notion API client wrapper to read/write ride data in a Notion database.
- send_summary.py        → Script that compiles metrics and sends the monthly summary email via Gmail SMTP.
- .github/workflows/monthly-summary.yml
→ GitHub Actions workflow that schedules and invokes send_summary.py on a monthly basis.
- requirements.txt, .gitignore, LICENSE, README.md
→ Configuration, dependency, and documentation files.

##### Main Architectural Components
a. Streamlit Dashboard (Budget.py)
- Interactive frontend served by Streamlit on a local or hosted server.
- Pulls ride data from Notion via Notion.py.
b. Notion Database (External Service)
- Stores raw ride/commute records.
- Exposed via the Notion API.
c. Email Service (External – Gmail SMTP)
- Receives summary payloads from send_summary.py.
- Sends monthly summary emails.
d. Automation Orchestrator (GitHub Actions)
- Triggers send_summary.py on a cron schedule (monthly).
- Runs in GitHub’s hosted runners.
e. Data Processing Layer (send_summary.py + Notion.py)
- Aggregates ride data, formats summary, and issues SMTP email calls.

##### Relationships and Data Flows
- User ↔ Streamlit App: HTTP client interaction for dashboards.
- Streamlit App → Notion API: Reads/writes ride records.
- GitHub Actions → send_summary.py: Scheduled execution.
- send_summary.py → Notion API: Fetches data for summaries.
- send_summary.py → Gmail SMTP: Pushes email content.
- Notion Database and Gmail SMTP sit outside your code and should be shown as “External Systems.”

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Budget.py for UI,
- Notion.py for data access,
- send_summary.py for reporting and notification.
- Modular Components: Each Python file encapsulates a distinct responsibility.
- “Serverless” Scheduler: Use of GitHub Actions to avoid self-hosting a cron job.
- Third-party Integration Pattern: Notion API client and SMTP as pluggable external services.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Title
    title["Hexz Drive Log System Architecture"]

    %% User
    User(("User")):::externalServices

    %% Python Application
    subgraph "Python Application"
        Budget["Streamlit Dashboard\n(Budget.py)"]:::pythonModules
        NotionModule["Notion Integration\n(Notion.py)"]:::pythonModules
        Summary["Summary Generator & Emailer\n(send_summary.py)"]:::pythonModules
    end

    %% External Services
    NotionAPI(["Notion API\n(External)"]):::externalServices
    Gmail(["Gmail SMTP\n(External)"]):::externalServices

    %% Scheduler
    Scheduler["GitHub Actions Scheduler\n(.github/workflows/monthly-summary.yml)"]:::scheduler

    %% Config & Documentation
    subgraph "Config & Documentation"
        Req["requirements.txt"]:::configDocs
        Gitignore[".gitignore"]:::configDocs
        Readme["README.md"]:::configDocs
        License["LICENSE"]:::configDocs
    end

    %% Data Flows
    User -->|Interacts| Budget
    Budget -->|Uses| NotionModule
    NotionModule -->|Queries| NotionAPI
    Scheduler -->|Triggers| Summary
    Summary -->|Fetches data| NotionModule
    Summary -->|Sends email| Gmail

    %% Click Events
    click Budget "https://github.com/iamhuzaifasabahuddin/hexz_automations/blob/main/Budget.py"
    click NotionModule "https://github.com/iamhuzaifasabahuddin/hexz_automations/blob/main/Notion.py"
    click Summary "https://github.com/iamhuzaifasabahuddin/hexz_automations/blob/main/send_summary.py"
    click Scheduler "https://github.com/iamhuzaifasabahuddin/hexz_automations/blob/main/.github/workflows/monthly-summary.yml"
    click Req "https://github.com/iamhuzaifasabahuddin/hexz_automations/blob/main/requirements.txt"
    click Gitignore "https://github.com/iamhuzaifasabahuddin/hexz_automations/blob/main/.gitignore"
    click Readme "https://github.com/iamhuzaifasabahuddin/hexz_automations/blob/main/README.md"
    click License "https://github.com/iamhuzaifasabahuddin/hexz_automations/tree/main/LICENSE"

    %% Styles
    classDef pythonModules fill:#D6EAF8,stroke:#2980B9,color:#1B4F72,stroke-width:2px;
    classDef externalServices fill:#D5F5E3,stroke:#27AE60,color:#1E8449,stroke-width:2px,stroke-dasharray: 5 5;
    classDef scheduler fill:#FCF3CF,stroke:#F1C40F,color:#B9770E,stroke-width:2px;
    classDef configDocs fill:#E8DAEF,stroke:#8E44AD,color:#512E5F,stroke-width:2px,dasharray:2 2;
```
