# cyrusimap/cyrus-imapd architecture

> Architecture diagram of the GitHub repository cyrusimap/cyrus-imapd, 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/cyrusimap/cyrus-imapd
- Repository: https://github.com/cyrusimap/cyrus-imapd

## Overview

Based on a careful analysis of the complete file tree and the README content, this project is the Cyrus IMAP Server – an email server with multiple protocol support (IMAP, JMAP, NNTP, POP3, CalDAV, CardDAV and WebDAV) and a highly modular design, built to run on sealed servers using its own private mailbox database. The system architecture reflects a layered server design with a master process coordinating multiple worker or protocol-specific processes, specialized storage backends (mailbox databases and indexes), and integrated support for auxiliary protocols and management utilities.

##### Main high-level components
- External Clients: Represent the various client groups (IMAP clients, JMAP clients, CalDAV/CardDAV clients, POP3, NNTP, and WebDAV users) that interact with the server.
- Protocol Frontends: Illustrate separate modules or services handling each protocol. For example, an IMAPd process for IMAP, HTTP endpoints (such as those in “imap/http_*.c” and “imap/jmap_*.c”) for JMAP and related protocols, as well as processes for POP3, NNTP, CalDAV, and CardDAV.
- Master Process: The “master” component (found in the master/ directory) which is responsible for overall process management, service coordination, and spawning appropriate protocol handlers.
- Auxiliary Services and Utilities: Include optional but important service components such as:
- notification services (notifyd directory)
- replication and synchronization components (e.g. in imap/replication, imap/sync_*.c)
- management scripts and tests (cassandane for automated testing, perl/sieve for sieve management, etc.) which show extensibility and testing layers.
- External Dependencies: Mark the reliance on external libraries and dependencies such as CyrusLibs (built from the cyruslibs repository) and optionally Xapian for advanced search indexing.

##### Relationships and interactions between these components
- Client connections flowing into the front-end protocol handlers.
- Demonstrate how the master process receives incoming connections and dispatches them to the appropriate protocol-specific worker processes.

##### Important architectural patterns
- Modularity & Separation of Concerns: Different protocols and functionalities are implemented in separate modules or executables.
- Process Management & Concurrency: The master process implements orchestration of worker processes, where concurrency is handled by forked child processes with access control and robust locking.
- Layered Security: The storage is “sealed” – accessed only through the server and controlled strictly by ACL and quota systems, emphasizing a clear separation between the underlying database and client interfaces.
- Extensibility: The directory structure shows separate areas for testing (cassandane, cunit, various “tiny-tests”), build scripts, and configuration examples – indicating that the system is built to be extensible and maintainable.

##### Essential architectural elements
- That the server supports multiple protocols and how the master process plays a central role.
- Integration points with external dependencies such as custom libraries built from cyruslibs, which must be accounted for by the build environment and runtime linking (as referenced in the README instructions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: External Clients
    Clients["External Clients"]:::client

    %% Protocol Frontends Layer
    subgraph "Protocol Frontends"
        IMAPd["IMAPd"]:::protocol
        JMAPHTTP["JMAP/HTTP Interfaces"]:::protocol
        POP3d["POP3d"]:::protocol
        NNTPd["NNTPd"]:::protocol
    end

    %% Master Process
    MasterProcess["Master Process"]:::master

    %% Internal Services Layer
    subgraph "Internal Services"
        MailboxStorage["Mailbox Storage"]:::storage
        AuthACL["Auth & ACL Module"]:::auth
        subgraph "Auxiliary Services"
            NotificationService["Notification Service"]:::auxiliary
            ReplicationModule["Replication Module"]:::auxiliary
            ManagementUtilities["Management & Testing Utilities"]:::auxiliary
        end
    end

    %% External Dependencies
    ExternalDeps["External Dependencies"]:::externalDep

    %% Connections from External Clients to Protocol Frontends
    Clients -->|"Client_Request"| IMAPd
    Clients -->|"Client_Request"| JMAPHTTP
    Clients -->|"Client_Request"| POP3d
    Clients -->|"Client_Request"| NNTPd

    %% Connections from Protocol Frontends to Master Process
    IMAPd -->|"Request"| MasterProcess
    JMAPHTTP -->|"Request"| MasterProcess
    POP3d -->|"Request"| MasterProcess
    NNTPd -->|"Request"| MasterProcess

    %% Connections from Master Process to Internal Services
    MasterProcess -->|"Mailbox_RW"| MailboxStorage
    MasterProcess -->|"Auth_Query"| AuthACL
    MasterProcess -->|"Notify"| NotificationService
    MasterProcess -->|"Replicate"| ReplicationModule
    MasterProcess -->|"Admin_Cmds"| ManagementUtilities

    %% Connections from Internal Services to External Dependencies
    MailboxStorage -->|"DB_Libs"| ExternalDeps
    AuthACL -->|"Auth_Libs"| ExternalDeps

    %% Click Events for Component Mapping
    click IMAPd "https://github.com/cyrusimap/cyrus-imapd/blob/master/imap/imapd.c"
    click JMAPHTTP "https://github.com/cyrusimap/cyrus-imapd/blob/master/imap/http_jmap.c"
    click POP3d "https://github.com/cyrusimap/cyrus-imapd/blob/master/imap/pop3d.c"
    click NNTPd "https://github.com/cyrusimap/cyrus-imapd/blob/master/netnews/nntpd.c"
    click MasterProcess "https://github.com/cyrusimap/cyrus-imapd/blob/master/master/master.c"
    click MailboxStorage "https://github.com/cyrusimap/cyrus-imapd/blob/master/imap/mailbox.c"
    click AuthACL "https://github.com/cyrusimap/cyrus-imapd/blob/master/lib/auth.c"
    click NotificationService "https://github.com/cyrusimap/cyrus-imapd/blob/master/notifyd/notifyd.c"
    click ReplicationModule "https://github.com/cyrusimap/cyrus-imapd/blob/master/imap/ctl_mboxlist.c"
    click ManagementUtilities "https://github.com/cyrusimap/cyrus-imapd/tree/master/cassandane/"
    click ExternalDeps "https://github.com/cyrusimap/cyrus-imapd/blob/master/lib/cyrusdb.c"

    %% Styles
    classDef client fill:#85C1E9,stroke:#2E86C1,stroke-width:2px;
    classDef protocol fill:#85C1E9,stroke:#2E86C1,stroke-width:2px;
    classDef master fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef storage fill:#82E0AA,stroke:#27AE60,stroke-width:2px;
    classDef auth fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef auxiliary fill:#D5D8DC,stroke:#A6ACAF,stroke-width:2px;
    classDef externalDep fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
```
