# stalwartlabs/mail-server architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source, all-in-one mail server supporting multiple mail protocols including JMAP, IMAP4/IMAP4rev2, POP3, SMTP, and ManageSieve.
- It incorporates numerous modern features such as spam/phishing filtering, security (TLS, DANE, MTA-STS, DMARC, DKIM, etc.), multi-tenancy, storage backends, and even a web-based administration dashboard.
- The README clearly states that the system is written in Rust and is built to be secure, fast, robust, and scalable.

##### Breakdown by Major Components (from the file tree and README)
- Multiple Protocol Servers:
- JMAP Server (found under crates/jmap and crates/jmap-proto)
- IMAP Server (crates/imap and crates/imap-proto)
- POP3 Server (crates/pop3)
- SMTP Server (crates/smtp)
- ManageSieve Server (crates/managesieve)
- Common Libraries and Shared Functionality:
- Common utilities, configuration, authentication, logging, and telemetry in crates/common.
- Utilities and helper functions in crates/utils.
- Tokenizers, NLP components in crates/nlp (used for spam filtering and language detection).
- Tracing and event logging functionality in crates/trc.
- Directory and Account Management:
- Crates/directory is responsible for account lookup through various backends (IMAP, LDAP, internal, etc).
- Email Handling:
- Crates/email handles email ingestion, delivery, indexing, and mailbox management.
- Storage Backends:
- Crates/store supports multiple storage backends (RocksDB, FoundationDB, PostgreSQL, MySQL, etc.) along with backends for blob storage, HTTP, and more.
- Spam Filtering:
- Crates/spam-filter provides spam classifier and rule-based filtering.
- Command Line Interface and Administration:
- Crates/cli provides command-line tools to interact with, configure, or maintain the mail server.
- External Resource & Configuration Files:
- Dockerfiles, CI workflows, and configuration in the resources folder indicate Docker/Kubernetes support and operational deployment.

##### Relationships and Data/Control Flows
- Clients (mail clients, web browsers, etc.) connect to protocol servers:
- For mail retrieval (IMAP/POP3) and sending (SMTP).
- JMAP clients interact with a dedicated JMAP API which also uses WebSocket and Sieve scripting.
- Each protocol server layer communicates with the underlying application logic in the common crate, which aggregates configuration, authentication, and business logic.
- The server components interface with storage backends (through crates/store) for persisting mail data, attachments, and metadata.
- A directory component manages account lookups and authentication (also interfacing with external systems like LDAP/OIDC if needed).
- Spam filtering operates during SMTP inbound (and possibly across protocols) to check messages using the spam-filter crate, integrating with NLP utilities where necessary.
- Management interfaces (likely accessed via a web-based admin console) interact with underlying management modules in directories like crates/main, crates/directory, and parts of crates/smtp (for queue/reporting management).

- Language: Rust (the project is implemented in Rust, using Rust’s package management with Cargo)
- Protocol-specific standards: RFC-driven implementations for JMAP, IMAP, POP3, SMTP, and ManageSieve.
- External protocols: TLS, OAuth2.0, OpenID Connect, ACME for certificate management.
- Observability: OpenTelemetry and Prometheus integrations.
- Storage: Options like RocksDB, PostgreSQL, MySQL, FoundationDB, SQLite, S3, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Clients["Clients (Mail Clients, Web Browsers)"]:::client

    %% Protocol Servers Subgraph
    subgraph "Protocol Servers"
        direction TB
        subgraph "JMAP Server"
            direction TB
            JMAP_Core["JMAP Core<br/>(Rust)"]:::protocol
            JMAP_Proto["JMAP Proto<br/>(Protocol)"]:::protocol
            JMAP_Core --> JMAP_Proto
        end
        subgraph "IMAP Server"
            direction TB
            IMAP_Core["IMAP Core<br/>(Rust)"]:::protocol
            IMAP_Proto["IMAP Proto<br/>(Protocol)"]:::protocol
            IMAP_Core --> IMAP_Proto
        end
        POP3["POP3 Server"]:::protocol
        SMTP["SMTP Server"]:::protocol
        Managesieve["ManageSieve Server"]:::protocol
    end

    %% Core Services Layer
    Common["Common Services<br/>(Config, Auth, Logging)"]:::service
    Directory["Directory & Account Mgmt"]:::service
    Email["Email Handling"]:::service
    Storage["Storage Backends"]:::database
    Spam["Spam Filtering & NLP"]:::service
    Admin["CLI & Administration"]:::service
    Observ["Observability & Telemetry"]:::service

    %% Arrows: Clients to Protocol Servers
    Clients -->|"JMAP API"| JMAP_Core
    Clients -->|"IMAP Data"| IMAP_Core
    Clients -->|"POP3 Requests"| POP3
    Clients -->|"SMTP - Inbound"| SMTP
    Clients -->|"Sieve Commands"| Managesieve

    %% Protocol Servers to Common Services
    JMAP_Core -->|"uses"| Common
    IMAP_Core -->|"uses"| Common
    POP3 -->|"uses"| Common
    SMTP -->|"uses"| Common
    Managesieve -->|"uses"| Common

    %% Common Services Flow
    Common -->|"auth lookup"| Directory
    Common -->|"email routing"| Email
    Email -->|"store data"| Storage

    %% SMTP integration with Spam Filtering
    SMTP -->|"spam check"| Spam
    Spam -->|"processed email"| Email

    %% Administration and Observability connections
    Admin -->|"config/control"| Common
    Common -->|"metrics"| Observ
    Directory -->|"logs"| Observ
    Email -->|"events"| Observ
    SMTP -->|"stats"| Observ

    %% Click Events for Component Mapping
    click JMAP_Core "https://github.com/stalwartlabs/mail-server/tree/main/crates/jmap"
    click JMAP_Proto "https://github.com/stalwartlabs/mail-server/tree/main/crates/jmap-proto"
    click IMAP_Core "https://github.com/stalwartlabs/mail-server/tree/main/crates/imap"
    click IMAP_Proto "https://github.com/stalwartlabs/mail-server/tree/main/crates/imap-proto"
    click POP3 "https://github.com/stalwartlabs/mail-server/tree/main/crates/pop3"
    click SMTP "https://github.com/stalwartlabs/mail-server/tree/main/crates/smtp"
    click Managesieve "https://github.com/stalwartlabs/mail-server/tree/main/crates/managesieve"
    click Common "https://github.com/stalwartlabs/mail-server/tree/main/crates/common"
    click Common "https://github.com/stalwartlabs/mail-server/tree/main/crates/utils"
    click Spam "https://github.com/stalwartlabs/mail-server/tree/main/crates/spam-filter"
    click Spam "https://github.com/stalwartlabs/mail-server/tree/main/crates/nlp"
    click Directory "https://github.com/stalwartlabs/mail-server/tree/main/crates/directory"
    click Email "https://github.com/stalwartlabs/mail-server/tree/main/crates/email"
    click Storage "https://github.com/stalwartlabs/mail-server/tree/main/crates/store"
    click Admin "https://github.com/stalwartlabs/mail-server/tree/main/crates/cli"
    click Admin "https://github.com/stalwartlabs/mail-server/tree/main/crates/main"
    click Observ "https://github.com/stalwartlabs/mail-server/tree/main/crates/trc"
    click Observ "https://github.com/stalwartlabs/mail-server/tree/main/crates/common/src/telemetry"

    %% Styles
    classDef client fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef protocol fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef service fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
```
