# frappe/mail architecture

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

- Interactive diagram: https://gitdiagram.com/frappe/mail
- Repository: https://github.com/frappe/mail

## Overview

- Frontend Client: Represented by the “frontend” directory. Note that it is built using Vue (files such as App.vue, multiple Vue components, and a Vite configuration). This part handles the Mail UI for composing, viewing (Inbox, Sent, Drafts), and managing emails.
- Backend Mail Processing: Represented by the “mail” folder. This is the core of the mail application and includes modules for the API (auth, outbound, inbound), handling email queues, and business logic (managing accounts, domains, aliases, groups, and various mail doctype operations).
- Mail Agent Integration: Show the integration with the external Stalwart Mail Server (referred to as “Mail Agent” within the README). Although it’s external, it is a crucial component for sending (SMTP) and receiving (IMAP) emails.
- Ancillary Modules: Include components such as the configuration files (ESLint, Prettier, commitlint), documentation (“docs” folder with screenshots and architecture images), and testing configurations as supporting pieces, though these might be less prominent in the high-level architecture.

##### Relationships and Data Flows
- Backend ↔ Mail Agent: Illustrate how outbound emails are pushed from the mail API to the Mail Agent (Stalwart Mail Server) using SMTP connection pooling; similarly, show how inbound emails are pulled back.
- DNS & Email Security: Acknowledge the use of DNS records (SPF, DKIM, DMARC) which are configured via the application. You might show a side note, indicating that when mail domains or accounts are configured (via the UI), appropriate DNS records are automatically created or need to be verified.

##### Architectural Patterns and Design Principles
- Modular Separation: Emphasize that the system is split into a clear separation of concerns – the presentation layer (frontend), the business logic/service layer (mail backend), and external services (Mail Agent).
- API-Driven: All functionalities for authentication, sending raw or formatted emails, and fetching inbound emails are available as RESTful API endpoints.
- Integration with Frappe Framework: Mention that the backend is built as a Frappe app, which might handle routing, templating, and multi-tenancy for email management.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend Layer
    subgraph "Frontend Layer"
        A["Frontend Client (Vue-based UI)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B["Backend API Endpoints (auth, outbound, inbound)"]:::backend
        C["Mail Business Logic (accounts,domains,aliases,groups)"]:::backend
        D["Queue Management"]:::backend
    end

    %% External Services
    subgraph "External Services"
        E["Mail Agent (Stalwart Mail Server)"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        F["Docker & Environment Setup"]:::infrastructure
        subgraph "Ancillary Modules"
            G["Docs"]:::ancillary
            J["Prettier Config"]:::ancillary
            K["ESLint Config"]:::ancillary
            L["Commitlint Config"]:::ancillary
        end
    end

    %% DNS & Email Security Note
    M["DNS & Email Security (SPF,DKIM,DMARC)"]:::ancillary

    %% Connections
    A -->|"APICall"| B
    B -->|"Routes"| C
    C -->|"QueuesEmail"| D
    C -->|"SMTP_IMAP"| E
    E -->|"InboundEmails"| C
    C -->|"Configures"| M

    %% Infrastructure Support Connections
    F -->|"Deploys"| A
    F -->|"Deploys"| B
    F -->|"Deploys"| E
    G -->|"DocsFor"| A
    G -->|"DocsFor"| B

    %% Styling
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef ancillary fill:#ffffcc,stroke:#000,stroke-width:2px;

    %% Click Events
    click A "https://github.com/frappe/mail/tree/develop/frontend/"
    click B "https://github.com/frappe/mail/tree/develop/mail/"
    click C "https://github.com/frappe/mail/tree/develop/mail/"
    click E "https://github.com/frappe/mail/blob/develop/mail/smtp.py"
    click F "https://github.com/frappe/mail/tree/develop/docker/"
    click G "https://github.com/frappe/mail/tree/develop/docs/"
    click J "https://github.com/frappe/mail/blob/develop/.prettierrc.json"
    click K "https://github.com/frappe/mail/blob/develop/eslint.config.mjs"
    click L "https://github.com/frappe/mail/blob/develop/commitlint.config.js"
```
