# rosehgal/trashemail architecture

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

- Interactive diagram: https://gitdiagram.com/rosehgal/trashemail
- Repository: https://github.com/rosehgal/trashemail

## Overview

##### Main Components
- TrashEmailService (Spring Boot Application):
– Contains the core business logic including creating email aliases and handling API requests.
– Houses controllers (e.g., TrashEmailResource), service layers, DTOs, repositories, and exception handling.
- EmailsToTelegramService:
– A microservice (or possibly a background service) responsible for polling the IMAP server, processing incoming email messages, and then routing them to the Telegram Bot.
- External Email Infrastructure:
– SMTP Server: Used for alias creation and deletion; the configuration specifies URLs for add/remove operations.
– IMAP Server: Supports the IDLE functionality for constantly listening for new emails.
- Telegram Bot API:
– Acts as the communication endpoint; incoming messages via Telegram are received through a webhook and outgoing messages are pushed to the user by the bot.
- MySQL Database:
– Persists data like user information, email allocations, and counters (noted by the spring.datasource config settings).
- Deployment and Integration Support:
– Docker (via Dockerfile and docker-compose.yml), Maven for build management, and shell scripts (build-and-run.sh) suggest containerization and automated deployment.
– Environment & configuration management files (EmailsToTelegramServiceConfig-*.yml and TrashEmailServiceConfig-*.yml) for tuning the service per deployment environment.

##### Relationships and Data Flow
- Telegram User Interaction:
– Users interact with the Telegram bot (@trashemail_bot).
– Telegram sends incoming requests to the web endpoint (e.g., /telegram/new-message) on TrashEmailService.
- TrashEmailService:
– Handles incoming requests, processes commands (e.g., create/delete disposable email aliases) and interacts with the SMTP server.
– Connects to the MySQL database to maintain state (such as allocated email aliases and user statistics).
- EmailsToTelegramService:
– Operates asynchronously to poll the IMAP server. When new mail arrives for an alias, it retrieves and routes the emails to the corresponding Telegram chat.
- External Dependencies:
– The SMTP server performs alias-related operations as requested by TrashEmailService.
– The IMAP server provides real-time email arrival notifications (using IDLE), triggering the email fetching service.

##### Architectural Patterns & Details to Highlight
- Microservices Architecture:
– Even though the project consists mainly of the TrashEmailService, its separation between the email alias management and the mail-fetching/sending service implies a loosely coupled design.
- Asynchronous & Event-Driven Processing:
– The background polling mechanism for the IMAP service represents an asynchronous, event-driven model – notify Telegram as soon as mail arrives.
- API Gateway-Like Interaction:
– The Telegram webhook endpoint plays a critical role and should be clearly represented as the gateway for incoming external requests.
- Configuration & Environment Separation:
– The presence of multiple configuration files for different environments (“dev”, “qa”, “prod”) indicates the importance of environment-specific tuning.

##### Final Elements
– Every component should have a clear title and a brief description (e.g., “TrashEmailService – Main API & alias management service”).
- Telegram Bot → (Webhook) TrashEmailService
- TrashEmailService → SMTP Server (for alias creation)
- TrashEmailService → MySQL Database (for persistence)
- IMAP Server → EmailsToTelegramService (email polling)
- EmailsToTelegramService → Telegram Bot (to notify users)

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction"
        TB["Telegram Bot API\n(Handles Messaging)"]:::external
    end

    %% Core Services Layer
    subgraph "Core Services"
        TES["TrashEmailService\n(Spring Boot API & alias management)"]:::service
        ET["EmailsToTelegramService\n(IMAP polling & Telegram routing)"]:::service
        ETI["EmailServerInteraction\n(Email Connectivity Logic)"]:::service
    end

    %% Email Infrastructure Layer
    subgraph "Email Infrastructure"
        SMTP["SMTP Server\n(Alias Creation/Deletion)"]:::external
        IMAP["IMAP Server\n(IDLE support)"]:::external
    end

    %% Persistence Layer
    subgraph "Persistence"
        DB["MySQL Database\n(Persistence)"]:::database
    end

    %% Deployment & Configuration Layer
    subgraph "Deployment & Configuration"
        DOCKERFILE["Dockerfile"]:::config
        DOCKERCOMPOSE["docker-compose.yml"]:::config
        CONFIG_TS["TrashEmailServiceConfig-sample.yml"]:::config
        CONFIG_ET["EmailsToTelegramServiceConfig-sample.yml"]:::config
    end

    %% Connections between layers
    TB -->|"webhook"| TES
    TES -->|"calls"| ETI
    ETI -->|"invokes"| SMTP
    TES -->|"aliasOps"| SMTP
    TES -->|"persists"| DB
    ET -->|"polls"| IMAP
    ET -->|"notifies"| TB

    %% Deployment and Config influences
    DOCKERFILE --> TES
    DOCKERFILE --> ET
    DOCKERCOMPOSE --> TES
    DOCKERCOMPOSE --> ET
    CONFIG_TS --> TES
    CONFIG_ET --> ET

    %% Styles
    classDef service fill:#ace,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
    classDef database fill:#f9c,stroke:#333,stroke-width:2px;
    classDef config fill:#ffc,stroke:#333,stroke-width:2px;

    %% Click Events
    click TES "https://github.com/rosehgal/trashemail/tree/master/TrashEmailService/"
    click ET "https://github.com/rosehgal/trashemail/tree/master/TrashEmailFetchMail/"
    click TB "https://github.com/rosehgal/trashemail/tree/master/TrashEmailTelegramConnector/"
    click ETI "https://github.com/rosehgal/trashemail/blob/master/TrashEmailService/src/main/java/io/github/trashemail/EmailServerInteraction.java"
    click DB "https://github.com/rosehgal/trashemail/blob/master/TrashEmailService/src/main/resources/application-sample.yml"
    click DOCKERFILE "https://github.com/rosehgal/trashemail/tree/master/TrashEmailService/Dockerfile"
    click DOCKERCOMPOSE "https://github.com/rosehgal/trashemail/blob/master/docker-compose.yml"
    click CONFIG_TS "https://github.com/rosehgal/trashemail/blob/master/TrashEmailServiceConfig-sample.yml"
    click CONFIG_ET "https://github.com/rosehgal/trashemail/blob/master/EmailsToTelegramServiceConfig-sample.yml"
```
