# mjl-/mox architecture

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

- Interactive diagram: https://gitdiagram.com/mjl-/mox
- Repository: https://github.com/mjl-/mox

## Overview

##### Main Components
a. Protocol Servers:
- SMTP Server – (found under “smtp”, “smtpserver”, “smtpclient”) handles receiving, submitting, and delivering email.
- IMAP Server – (directories “imapserver”, “imapclient”) provides access to mailboxes via IMAP.
b. Web Interfaces & APIs:
- Webmail – (in “webmail”) is the browser-based email client.
- Admin & Webadmin – (directories “admin”, “webadmin”) supply an administrative interface for configuring domains, accounts, and managing settings.
- Web API & Webhooks – (found in “webapi”, “webapisrv”) offer HTTP/JSON endpoints for transactional email and delivery events.
c. Mail Authentication & Security:
- DKIM, DMARC, SPF – (directories “dkim”, “dmarc”, “spf”) implement signing/verification and reputation/tracking logic.
- DNS/DANE – (directories “dns”, “dane”, “dnsbl”) support DNS lookups, DANE and blocklist mechanisms.
d. TLS and Automatic Certificate Management:
- Autotls – (directory “autotls”) handles automatic TLS certificate generation (ACME integration).
e. Data Storage & Processing:
- Message Storage, Indexing, and Queuing – (directories “store”, “queue”, “message”) indicate how mail messages are stored on disk and indexed (using bbolt via the “bstore” library).
- Metrics & Logging – (files like “metrics.go”, “mlog”) provide operational insights.
f. Auxiliary and Integrations:
- Tools for backup, API documentation generation, and testing (e.g. “apidiff”, “gendoc.sh”, “testdata”) indicate operational support.
- Docker and deployment scripts (Dockerfiles, docker-compose files) denote deployment architecture.
- External integrations for ACME, Prometheus, etc., are also key players.

##### Relationships and Interactions
- External Clients (Mail user agents, web browsers, mobile apps) interact via different protocols:
– SMTP clients send outgoing mail to the SMTP server.
– IMAP clients retrieve emails from the IMAP server.
– Web users connect to the webmail or admin interfaces (served by the embedded webserver).
– External applications use REST/JSON APIs via the web API endpoints.
- The protocol servers (SMTP/IMAP) communicate with the core mail processing modules:
– Incoming email messages are processed (authenticated, possibly spam/virus checked, and passed on to the mail storage engine) and metadata is saved in the indexing databases.
- The authentication/security libraries (DKIM, DMARC, SPF) work as intermediaries during mail processing, verifying and tagging email authenticity.
- The automatic TLS component communicates with external Certificate Authorities (e.g. Let’s Encrypt) through ACME protocols.
- The configuration (from “config”) and backup data (from “store”, “queue”) are centrally managed and used by almost every module.
- The webserver (serving admin interfaces and webmail) shares the same TLS certificates and configuration as the rest of the system.
- Monitoring and metrics are exported (using Prometheus and structured logging) from the core components.

##### Architectural Patterns and Design Principles
- Modular design: Each protocol or service is implemented in its own package and directory, promoting separation of concerns.
- Layered architecture:
– Presentation Layer: Webmail, admin UI, API endpoints.
– Service/Protocol Layer: SMTP and IMAP servers.
– Core Processing Layer: Message handling, spam filtering, reputation tracking, authentication (DKIM/DMARC/SPF) and TLS/ACME.
– Data Storage Layer: File-based mail storage, bbolt databases via “bstore”, queues, and logs.
- Loose coupling via configuration files and externalized components (such as transports) that allow mox to work in a self‐contained style while still being customizable.

##### Elements
– SMTP Server (with subcomponents for submission, rate limiting, reputation filtering)
– IMAP Server and client interaction modules
– Webmail Interface & Admin Dashboard
– HTTP/JSON API (webapisrv)
– Mail Processing & Message Queue (queue, message) and Data Storage (store)
– Security/Validation modules (dkim, dmarc, spf)
– TLS/ACME and Automatic Certificate Management (autotls)
– DNS/DANE modules (dns, dane, dnsbl)
– Monitoring & Metrics (Prometheus integration)
- Notations for external interactions: Internet (for inbound/outbound mail), CA (for TLS), external email providers, and so on.

##### Final Advice for the Principal Software Engineer
- While the project structure is large, do not shy away from decomposing it into as many components as possible – this will help reveal dependencies and data flows very accurately.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        EC("External Clients"):::external
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        SMTP("SMTP Server"):::protocol
        IMAP("IMAP Server"):::protocol
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        Webmail("Webmail Interface"):::presentation
        Admin("Admin Interfaces"):::presentation
        API("Web API & Webhooks"):::presentation
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        DKIM("Mail Authentication (DKIM)"):::core
        DMARC("Mail Authentication (DMARC)"):::core
        SPF("Mail Authentication (SPF)"):::core
        DNS("DNS/DANE & Blocklists"):::core
        TLS("TLS/ACME Automatic Certificate Management"):::core
    end

    %% Data Storage & Monitoring
    subgraph "Data Storage & Monitoring"
        Storage("Message Storage, Indexing & Queueing"):::storage
        Metrics("Metrics & Logging"):::storage
    end

    %% Auxiliary Tools & Integrations
    subgraph "Auxiliary Tools & Integrations"
        Aux("Auxiliary Tools & Integrations"):::auxiliary
    end

    %% External Certificate Authority
    CA("CA (Let's Encrypt)"):::externalService

    %% Connections from External Clients
    EC --> SMTP
    EC --> IMAP
    EC --> Webmail
    EC --> Admin
    EC --> API

    %% Protocol Layer interactions
    SMTP -->|"authenticates"| DKIM
    SMTP -->|"authenticates"| DMARC
    SMTP -->|"authenticates"| SPF
    SMTP -->|"DNSlookup"| DNS
    SMTP -->|"securedby"| TLS
    IMAP -->|"securedby"| TLS
    IMAP -->|"fetches"| Storage

    %% Presentation Layer interactions
    Webmail -->|"securedby"| TLS
    Admin -->|"securedby"| TLS
    API -->|"securedby"| TLS

    %% Core Processing to Data Storage
    DKIM -->|"stores"| Storage
    DMARC -->|"stores"| Storage
    SPF -->|"stores"| Storage

    %% TLS interactions
    TLS -->|"reqcert"| CA

    %% Logging and Metrics
    SMTP -->|"logs"| Metrics
    IMAP -->|"logs"| Metrics
    Webmail -->|"logs"| Metrics
    Admin -->|"logs"| Metrics
    API -->|"logs"| Metrics
    Storage -->|"monitoredby"| Metrics

    %% Auxiliary Tools support
    Aux -->|"supports"| Storage
    Aux -->|"supports"| Metrics

    %% Click Events
    click SMTP "https://github.com/mjl-/mox/tree/main/smtp"
    click IMAP "https://github.com/mjl-/mox/tree/main/imapserver"
    click Webmail "https://github.com/mjl-/mox/tree/main/webmail"
    click Admin "https://github.com/mjl-/mox/tree/main/admin"
    click API "https://github.com/mjl-/mox/tree/main/webapi"
    click DKIM "https://github.com/mjl-/mox/tree/main/dkim"
    click DMARC "https://github.com/mjl-/mox/tree/main/dmarc"
    click SPF "https://github.com/mjl-/mox/tree/main/spf"
    click DNS "https://github.com/mjl-/mox/tree/main/dns"
    click TLS "https://github.com/mjl-/mox/tree/main/autotls"
    click Storage "https://github.com/mjl-/mox/tree/main/store"
    click Metrics "https://github.com/mjl-/mox/blob/main/metrics.go"
    click Aux "https://github.com/mjl-/mox/tree/main/apidiff"

    %% Styles
    classDef external fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef protocol fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef presentation fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef core fill:#ffebcc,stroke:#333,stroke-width:2px;
    classDef storage fill:#ffe6ff,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#e6e6e6,stroke:#333,stroke-width:2px;
    classDef externalService fill:#faffbd,stroke:#333,stroke-width:2px;
```
