# priyadharshanr31/email-processor architecture

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

- Interactive diagram: https://gitdiagram.com/priyadharshanr31/email-processor
- Repository: https://github.com/priyadharshanr31/email-processor

## Overview

##### Main Components
- Email Fetcher/Processor: Represented by email_processor.py. This module connects to the email server (using IMAP via imaplib) and extracts attachments from unread emails matching a specific subject.
- Email Sender: Represented by email_sender.py. This component creates and sends the processed file back to the sender (using smtplib, email, and mimetypes).
- File Processor: Represented by process_files.py. It handles reading the downloaded Excel file, applying the filter (e.g., based on a “Status” column), and merging the data into the predefined template (template.xlsx) using libraries like pandas and openpyxl.
- Streamlit UI: Defined in streamlit_ui.py. It provides an interactive interface for the user to preview data and specify the location where processed data should be inserted in the template.
- Configuration Module: config.py contains the email credentials and other settings that tailor the behavior of the email processor and sender.
- External Artifacts:
- Attachments Folder: Holds downloaded email attachments.
- Output Folder: Stores the processed files that have been merged with the template.
- Template File: template.xlsx serves as the baseline to which new data is added.

##### Relationships and Interactions
- The Email Processor connects to the email server where it finds unread emails and downloads Excel attachments into the attachments folder.
- The File Processor then reads these attachments, applies the data filter (based on criteria in process_files.py), and merges it into the template provided.
- The processed output is saved in the output folder.
- Finally, the Email Sender picks up this processed file and sends it back to the original sender, completing the loop.
- The config.py file is used by both email_processor.py and email_sender.py to configure connection and authentication parameters.

##### Architectural Patterns and Design Principles
- Modular Design: The project is clearly divided into small, single-responsibility modules (each Python file handles a specific aspect of the workflow).
- Pipeline Flow: The design envisions a linear, multi-stage workflow (from email fetching, data extraction/processing, to email sending) that can be visualized as sequential layers.
- UI-Backend Separation: The Streamlit UI (frontend) acts as a trigger or dashboard interface while all the heavy lifting is done in the backend scripts.

- Pipeline nature: starting with email fetching, then processing (data extraction and merging), and finally sending the processed file.
- How the Streamlit UI integrates with the processing flow by enabling the user to preview and adjust the inserted data position in the template.
- Use of key libraries like pandas and openpyxl in the data processing block, and imaplib/email/smtplib in the email interactions.
- That all key files and directories (attachments, output, and the template) are represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    ES["Email Server"]:::external

    %% Processing Modules
    EP["Email Processor"]:::backend
    FP["File Processor"]:::backend
    ESd["Email Sender"]:::backend
    CFG["Configuration"]:::config

    %% Storage and Artifacts
    AF["Attachments Folder"]:::storage
    OF["Output Folder"]:::storage
    TMP["Template"]:::storage

    %% User Interface
    UI["Streamlit UI"]:::ui

    %% Data Flow
    ES -->|"fetchesEmails"| EP
    EP -->|"downloadsAttachments"| AF
    AF -->|"sendsToProcess"| FP
    FP -->|"mergesDataWith"| TMP
    FP -->|"savesProcessedFile"| OF
    OF -->|"initiatesEmailSending"| ESd
    ESd -->|"sendsBackTo"| ES
    UI -->|"triggersProcessAndPreview"| FP
    FP -->|"updatesPreview"| UI

    %% Configuration Associations
    EP ---|"uses"| CFG
    ESd ---|"uses"| CFG

    %% Click Events
    click EP "https://github.com/priyadharshanr31/email-processor/blob/main/email_processor.py"
    click ESd "https://github.com/priyadharshanr31/email-processor/blob/main/email_sender.py"
    click FP "https://github.com/priyadharshanr31/email-processor/blob/main/process_files.py"
    click UI "https://github.com/priyadharshanr31/email-processor/blob/main/streamlit_ui.py"
    click CFG "https://github.com/priyadharshanr31/email-processor/blob/main/config.py"
    click TMP "https://github.com/priyadharshanr31/email-processor/blob/main/template.xlsx"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef backend fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef ui fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef storage fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef config fill:#FFE4B5,stroke:#333,stroke-width:2px;
```
