# cocoanetics/swiftmail architecture

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

- Interactive diagram: https://gitdiagram.com/cocoanetics/swiftmail
- Repository: https://github.com/cocoanetics/swiftmail

## Overview

- Core Email Functionality (Sources/SwiftMail/Core) – This includes command handlers, logging utilities, and email model definitions.
- IMAP Module (Sources/SwiftMail/IMAP) – Consists of:
- IMAP Protocol Commands and Handlers (in both “Commands” and “Handler” directories)
- IMAP models (Mailbox, Message, Header, etc.)
- Supporting extensions and error handling (e.g., IMAPError, UndefinedFolderError)
- The overall IMAPServer component which integrates connection handling, authentication, and TLS support.
- SMTP Module (Sources/SwiftMail/SMTP) – Contains:
- SMTP commands and their associated handlers for tasks like AUTH, EHLO, DATA, etc.
- SMTP core response processing and error handling (e.g., SMTPResponse, SMTPError)
- TLS and authentication mechanisms (including multiple auth methods)
- The SMTPServer component that manages email sending.
- Demos (SwiftIMAPCLI and SwiftSMTPCLI in the Demos directory) – These provide example implementations and use .env configuration indicating their dependency on runtime configuration.
- Tests – Represent various testing strategies applied across the modules (IMAP, SMTP, and Core functionalities).

##### Relationships and Data Flows
- External dependency flows by drawing connections from the core components (IMAPModule and SMTPModule) to external libraries such as SwiftNIO, SwiftNIOSSL, and Swift Logging.
- That the Core module provides shared models and utilities to both the IMAP and SMTP modules.
- Configuration flow (via the .env file) that feeds into the demos at startup.
- Interactions within each server (e.g., IMAP commands route to specific command handlers in a request–response pattern; similarly, SMTP commands flow through various authentication and content handlers).

##### Architectural Patterns and Design Principles
- Component-based modular design: Separate IMAP and SMTP into distinct modules using similar internal structures (Commands, Handlers, Models), ensuring a clear separation of concerns.
- Use of protocol-oriented programming – especially evident in the “Protocols” directories where abstractions for commands and handlers have been defined.
- Configuration-based behavior for the command line demos, which use environment variables to drive runtime behavior.
- Leverage dependency injection patterns (either explicitly or implicitly) by passing configurations, and integrating external Swift packages.

##### Incorporate Key Technologies, Frameworks, and Libraries
- SwiftNIO and SwiftNIOSSL for network communication and secure connections.
- Swift Logging components for debug and production logging.
- Reference the dependency on SwiftDotenv for CLI configuration management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Email Library Subgraph
    subgraph "Email Library"
        coreModule["Core Email Module"]:::core

        subgraph "IMAP Module"
            imapCommands["IMAP Commands"]:::imap
            imapHandlers["IMAP Handlers"]:::imap
            imapModels["IMAP Models"]:::imap
            imapExtensions["IMAP Extensions"]:::imap
            imapServer["IMAP Server"]:::imap
            imapErrors["IMAP Errors"]:::imap
        end

        subgraph "SMTP Module"
            smtpCommands["SMTP Commands"]:::smtp
            smtpHandlers["SMTP Handlers"]:::smtp
            smtpCore["SMTP Core"]:::smtp
            smtpServer["SMTP Server"]:::smtp
            smtpErrors["SMTP Errors"]:::smtp
        end
    end

    %% CLI Demos Subgraph
    subgraph "CLI Demos"
        imapCLI["SwiftIMAPCLI Demo"]:::demos
        smtpCLI["SwiftSMTPCLI Demo"]:::demos
    end

    %% Environment Configuration and Tests
    configNode["Environment Configuration"]:::config
    testsNode["Tests"]:::tests

    %% External Libraries Subgraph
    subgraph "External Libraries"
        nio["SwiftNIO"]:::external
        niossl["SwiftNIOSSL"]:::external
        logging["Swift Logging"]:::external
        dotenv["SwiftDotenv"]:::external
    end

    %% Relationships: Demos to Servers
    imapCLI -->|"calls"| imapServer
    smtpCLI -->|"calls"| smtpServer

    %% Relationships: Servers to Core Module
    imapServer -->|"uses"| coreModule
    smtpServer -->|"uses"| coreModule

    %% Relationships: Server internal flow (IMAP)
    imapServer -->|"routesTo"| imapCommands
    imapServer -->|"routesTo"| imapHandlers
    imapServer -->|"handles"| imapErrors

    %% Relationships: Server internal flow (SMTP)
    smtpServer -->|"routesTo"| smtpCommands
    smtpServer -->|"routesTo"| smtpHandlers
    smtpServer -->|"processes"| smtpCore
    smtpServer -->|"handles"| smtpErrors

    %% Relationships: External Libraries
    imapServer -->|"netLib"| nio
    imapServer -->|"tlsLib"| niossl
    imapServer -->|"logLib"| logging
    smtpServer -->|"netLib"| nio
    smtpServer -->|"tlsLib"| niossl
    smtpServer -->|"logLib"| logging
    imapCLI ---|"config"| configNode
    smtpCLI ---|"config"| configNode

    %% Relationships: Tests verifying modules
    testsNode ---|"testsCore"| coreModule
    testsNode ---|"testsIMAP"| imapServer
    testsNode ---|"testsSMTP"| smtpServer

    %% Click Events
    click coreModule "https://github.com/cocoanetics/swiftmail/tree/main/Sources/SwiftMail/Core"
    click imapCommands "https://github.com/cocoanetics/swiftmail/tree/main/Sources/SwiftMail/IMAP/IMAP/Commands"
    click imapHandlers "https://github.com/cocoanetics/swiftmail/tree/main/Sources/SwiftMail/IMAP/IMAP/Handler"
    click imapModels "https://github.com/cocoanetics/swiftmail/tree/main/Sources/SwiftMail/IMAP/Models"
    click imapExtensions "https://github.com/cocoanetics/swiftmail/tree/main/Sources/SwiftMail/IMAP/Extensions"
    click imapServer "https://github.com/cocoanetics/swiftmail/blob/main/Sources/SwiftMail/IMAP/IMAPServer.swift"
    click imapErrors "https://github.com/cocoanetics/swiftmail/blob/main/Sources/SwiftMail/IMAP/IMAPError.swift"
    click smtpCommands "https://github.com/cocoanetics/swiftmail/tree/main/Sources/SwiftMail/SMTP/Commands"
    click smtpHandlers "https://github.com/cocoanetics/swiftmail/tree/main/Sources/SwiftMail/SMTP/Handlers"
    click smtpCore "https://github.com/cocoanetics/swiftmail/tree/main/Sources/SwiftMail/SMTP/Core"
    click smtpServer "https://github.com/cocoanetics/swiftmail/blob/main/Sources/SwiftMail/SMTP/SMTPServer.swift"
    click smtpErrors "https://github.com/cocoanetics/swiftmail/blob/main/Sources/SwiftMail/SMTP/SMTPError.swift"
    click imapCLI "https://github.com/cocoanetics/swiftmail/tree/main/Demos/SwiftIMAPCLI"
    click smtpCLI "https://github.com/cocoanetics/swiftmail/tree/main/Demos/SwiftSMTPCLI"
    click configNode "https://github.com/cocoanetics/swiftmail/blob/main/.env.example"
    click testsNode "https://github.com/cocoanetics/swiftmail/tree/main/Tests"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef imap fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef smtp fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef demos fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef config fill:#D5DBDB,stroke:#808B96,stroke-width:2px;
    classDef tests fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
```
