# zamalali/inboxhero architecture

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

- Interactive diagram: https://gitdiagram.com/zamalali/inboxhero
- Repository: https://github.com/zamalali/inboxhero

## Overview

##### Main Components
- User Interface:
- Streamlit frontend (the entry point is src/app.py). This is where the user interacts with the app and triggers operations like email prioritization, reply detection, and interactive chat.
- Email Ingestion and Integration:
- A component that connects to Gmail via the Gmail API. This module authenticates using the client_secret.json (which must be uploaded when running the app) and retrieves emails.
- Email Processing Module:
- NLP and Summarization Engine:
- Integration with Langchain and ChatGroq. This engine handles summarization of email bodies and the generation of draft responses.
- Attachment Processing Module:
- There is support for Microsoft attachments like PDFs, DOCX, and Excel files. This module reads, parses, and summarizes attachments.
- Utilities and Helper Functions:
- Library of utility functions found under src/utils (attachment.py, tool.py, utils.py). These are used to modularize operations like email processing, attachment reading, and other non-UI logic.
- External Services and Configurations:
- External configuration management (.env file for API keys) and the dependencies setup (requirements.txt). Also note external API integration with both Gmail and Groq.

##### Relationships and Interactions
- Communications from the Email Processing component to the NLP and Summarization Engine (Langchain/ChatGroq), indicating that email contents are sent for summarization and draft generation.

##### Architectural Choices and Design Principles
- The design is modular and separates the concerns between UI (Streamlit), backend processing (email and attachment processing), and external integrations (Gmail API and Langchain/ChatGroq).
- That the utilities—grouped under src/utils—make it easier to maintain and extend the functionality, fitting a clean separation of concerns.
- While the project isn’t built in a full-blown layered architecture (like traditional MVC), it still distinctly separates user interface from business logic and third-party API integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% UI Layer
    subgraph "User Interface Layer"
        UI["Streamlit Frontend (src/app.py)"]:::ui
    end

    %% Email Integration Layer
    subgraph "Email Integration"
        Gmail["Gmail API Integration"]:::integration
        Config["API Keys & Client Secrets"]:::config
    end

    %% Processing Modules
    subgraph "Processing Modules"
        EmailProc["Email Processing Module (Ranking & Reply Detection)"]:::process
        NLPEngine["NLP & Summarization Engine (Langchain/ChatGroq)"]:::process
        AttachProc["Attachment Processing Module (MS Attachments)"]:::process
        ToolUtil["Tool Utilities"]:::utils
        CommonUtil["Common Utilities"]:::utils
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Dep["Dependencies (.env & requirements.txt)"]:::external
        Documentation["Documentation (README.md)"]:::external
    end

    %% Data Flow
    UI -->|"triggers"| Gmail
    UI -->|"initiates processing"| EmailProc
    Gmail -->|"passes emails"| EmailProc
    Config ---|"provides creds"| Gmail
    EmailProc -->|"sends content"| NLPEngine
    NLPEngine -->|"returns summaries/drafts"| EmailProc
    EmailProc -->|"invokes"| AttachProc
    AttachProc -->|"processes attachments"| EmailProc
    ToolUtil ---|"supports"| EmailProc
    CommonUtil ---|"supports"| EmailProc
    EmailProc -->|"displays results"| UI

    %% External dependencies linkage
    Dep ---|"configures"| Config
    Documentation ---|"guides configuration"| Config

    %% Click Events
    click UI "https://github.com/zamalali/inboxhero/blob/main/src/app.py"
    click Config "https://github.com/zamalali/inboxhero/blob/main/.env"
    click Documentation "https://github.com/zamalali/inboxhero/blob/main/README.md"
    click AttachProc "https://github.com/zamalali/inboxhero/blob/main/src/utils/attachment.py"
    click ToolUtil "https://github.com/zamalali/inboxhero/blob/main/src/utils/tool.py"
    click CommonUtil "https://github.com/zamalali/inboxhero/blob/main/src/utils/utils.py"
    click Dep "https://github.com/zamalali/inboxhero/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef integration fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef config fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef process fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef utils fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef external fill:#F0E68C,stroke:#000,stroke-width:2px;
```
