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: roughly 45 containers in the full production stack, but organized into a handful of clear layers.

Each layer only talks to the layers it needs to. Workers never handle raw SMTP. Postfix never queries Qdrant. This keeps the system modular — services can be scaled or restarted independently of mail delivery.

System Diagram¶

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

    subgraph Edge["Edge (production)"]
        Traefik["Traefik<br>:80 :443"]
    end

    subgraph Mail["Mail Infrastructure"]
        Postfix["Postfix<br>SMTP :25 :587 :465"]
        Dovecot["Dovecot<br>IMAP :143 :993<br>POP3 :110 :995 · Sieve :4190"]
        Rspamd["Rspamd<br>milter :11332<br>(spam + DKIM signing)"]
        CertMgr["cert_manager"]
        LogIngestor["log_ingestor<br>(mail.log → mail_logs)"]
    end

    subgraph API["API Gateway + Workers"]
        Gateway["FastAPI Gateway (api)<br>:8080 · 34 route modules"]
        Webhooks["webhooks"]
        Tracking["tracking"]
        RateLimiter["rate_limiter"]
        Analytics["analytics"]
        QueueMgr["queue_manager"]
        StorageUsage["storage_usage"]
        Archiver["archiver"]
        RAG["rag"]
        More["autoconfig · jmap · caldav<br>oauth · migration · templates<br>url_protection · delivery_optimizer<br>encryption · activesync · dashboard<br>monitoring · dlp · totp · geo_blocking"]
    end

    subgraph Data["Data Stores"]
        MySQL[("MySQL")]
        Redis[("Redis")]
        Qdrant[("Qdrant")]
        S3[("S3 object storage")]
    end

    Internet -->|"SMTP :25"| Postfix
    Clients -->|"IMAP/POP3"| Dovecot
    Clients -->|"SMTP submit :587/:465"| Postfix
    Upstream -->|"HTTPS"| Traefik
    Browser -->|"HTTPS"| Traefik
    Traefik -->|"api.domain"| Gateway

    Postfix -->|"milter"| Rspamd
    Postfix -->|"LMTP :24"| Dovecot
    Postfix -->|"policy check"| RateLimiter
    Postfix -->|"content filter"| Tracking
    Dovecot -->|"auth + accounts"| MySQL
    Dovecot -->|"sieve archive copy"| Archiver
    LogIngestor --> MySQL
    CertMgr --> Postfix
    CertMgr --> Dovecot

    Gateway -->|"SMTP :10587"| Postfix
    Gateway --> MySQL
    Gateway --> Redis
    Gateway -->|"proxies"| Tracking
    Gateway -->|"proxies"| Analytics
    Gateway -->|"proxies"| RateLimiter
    Gateway -->|"proxies"| QueueMgr

    Tracking --> MySQL
    Webhooks --> MySQL
    Analytics --> MySQL
    RAG --> Qdrant
    Archiver --> S3
    StorageUsage -->|"IMAP QUOTA"| Dovecot
    QueueMgr -->|"shared spool"| Postfix

Service inventory¶

The full roster lives in Service Architecture, with per-service detail. The short version, straight from docker-compose.yml:

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