Architecture Overview¶

A bird's-eye view of how Mailyte's email server is put together and why each piece exists. If you want to understand the system before you start building on it, this is the place.

In this section¶

The Big Picture¶

Mailyte is a multi-tenant email server that sends, receives, filters, and stores email for multiple organizations — all from a single deployment. Think of it as running a small email hosting company inside a Docker Compose stack.

The system breaks down into three layers, each with a clear job:

Each layer only talks to the layers it needs to. Workers never handle raw SMTP. Postfix never queries Qdrant. This keeps the system modular — you can swap out Redis for another cache, or scale the workers independently of the mail servers.

System Diagram¶

graph TB
    subgraph External
        Internet["Internet / Remote MTAs"]
        Clients["Email Clients<br>(Thunderbird, Outlook, etc.)"]
        Upstream["Upstream Systems<br>(your app)"]
    end

    subgraph Mail["Mail Infrastructure Layer"]
        Postfix["Postfix<br>SMTP :25 :587 :465"]
        Dovecot["Dovecot<br>IMAP :143 :993<br>POP3 :110 :995"]
        Rspamd["Rspamd + ClamAV<br>:11332"]
    end

    subgraph API["API + Workers Layer"]
        FastAPI["FastAPI REST API<br>:5000"]
        Health["Health Monitor<br>:8080"]
        Tracking["Tracking Worker"]
        Webhooks["Webhook Worker"]
        RateLimiter["Rate Limiter"]
        Analytics["Analytics Worker"]
        RAG["RAG Worker"]
        QueueMgr["Queue Manager"]
        StorageUsage["Storage Usage"]
        Backup["Backup Worker"]
        CloudSync["Cloud Sync"]
        LogAnalyzer["Log Analyzer"]
        CertMgr["Cert Manager"]
        IDS["Intrusion Detection<br>(fail2ban)"]
    end

    subgraph Data["Data Stores Layer"]
        MySQL["MySQL"]
        Redis["Redis"]
        Qdrant["Qdrant<br>Vector DB"]
    end

    Internet -->|"SMTP"| Postfix
    Clients -->|"IMAP/POP3"| Dovecot
    Clients -->|"SMTP submit"| Postfix
    Upstream -->|"REST"| FastAPI

    Postfix -->|"spam check"| Rspamd
    Postfix -->|"deliver"| Dovecot
    Dovecot -->|"auth lookup"| MySQL

    FastAPI --> MySQL
    FastAPI --> Redis
    FastAPI --> Qdrant

    Tracking --> MySQL
    Tracking --> Redis
    Webhooks --> MySQL
    Webhooks --> Redis
    Analytics --> MySQL
    Analytics --> Redis
    RAG --> Qdrant
    RAG --> MySQL
    QueueMgr --> Redis
    QueueMgr --> MySQL
    QueueMgr --> Postfix
    RateLimiter --> Redis
    StorageUsage --> MySQL
    Backup --> MySQL
    LogAnalyzer --> MySQL
    CertMgr --> Postfix
    CertMgr --> Dovecot
    IDS --> Redis
    Health --> MySQL
    Health --> Redis
    Health --> Postfix
    Health --> Dovecot

Service inventory¶

Every service in the stack at a glance:

How the Layers Talk to Each Other¶

Multi-Tenancy at a Glance¶

Every piece of data belongs to an Organization. Organizations own Domains. Domains own Email Accounts and Aliases. This hierarchy means you can host acme.com and widgets.io under different organizations with fully isolated data, quotas, and rate limits — all in the same deployment.

graph TD
    Org["Organization<br><em>acme-corp</em>"] --> DomainA["Domain<br><em>acme.com</em>"]
    Org --> DomainB["Domain<br><em>acme.io</em>"]
    DomainA --> Mailbox1["Mailbox<br><em>alice@acme.com</em>"]
    DomainA --> Mailbox2["Mailbox<br><em>bob@acme.com</em>"]
    DomainA --> Alias1["Alias<br><em>info@acme.com → alice</em>"]
    DomainB --> Mailbox3["Mailbox<br><em>support@acme.io</em>"]
    style Org fill:#4051b5,color:#fff
    style DomainA fill:#2e7d32,color:#fff
    style DomainB fill:#2e7d32,color:#fff

For the full breakdown, see Organization Model and Multi-Tenant Isolation.

Key design decisions¶

What to Read Next¶

Related sections:

• Getting Started -- install and run the stack
• API Reference -- interact with the control plane
• Security -- deep dive into every defense layer