# zone-eu/zonemta-wildduck architecture

> Architecture diagram of the GitHub repository zone-eu/zonemta-wildduck, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zone-eu/zonemta-wildduck
- Repository: https://github.com/zone-eu/zonemta-wildduck

## Overview

##### Project type and purpose
- This is a Node.js plugin module (“zonemta-wildduck”) that extends ZoneMTA (an SMTP server) with WildDuck authentication and delivery features.
- Its primary role is to sit inside ZoneMTA as an MSA (Mail Submission Agent) plugin, enforce user‐based sending restrictions, rewrite message headers, upload sent mail to IMAP, and decide whether to hand off locally or via MX.

##### File structure
- Top-level files:
– index.js: the plugin entry point where it registers hooks with ZoneMTA
– config.example.toml: plugin configuration schema (authentication toggles, mailbox limits, LMTP settings)
– package.json & lock: NPM metadata and dependency lockfile
– Dockerfile, Gruntfile.js, .github/workflows/*: CI/CD and build/test pipelines (unit tests, linting, releases)
- Lint & formatting: .eslintrc, .prettierrc.js, .ncurc.js
- GitHub workflows for testing and Docker image creation indicate it can be deployed as a containerized plugin.

##### README for insights
- Describes five core features: authentication, From rewriting, “Sent Mail” upload, recipient rate limiting, and local LMTP delivery.
- Shows integration points: SMTP interface of ZoneMTA (port 587), WildDuck user store (via its HTTP or IMAP API), and LMTP for local delivery.
- Configuration driven by TOML options.

a. Main components:
– SMTP Client (e.g., mail user agent)
– ZoneMTA SMTP Interface (port 587)
– zonemta-wildduck Plugin (index.js logic)
– WildDuck Server (authentication API + IMAP storage)
– LMTP Server (for local delivery)
– DNS/MX lookup (for remote delivery)
– Configuration Store (config.example.toml)
b. Relationships & data flows:
1. SMTP Client → ZoneMTA
2. ZoneMTA invokes zonemta-wildduck plugin hooks
3. Plugin → WildDuck authentication API (check credentials)
4. Plugin rewrites From header if needed
5. Plugin → WildDuck IMAP “Sent Mail” append
6. Plugin decides:
- If recipient domain hosted locally → LMTP Server
- Else → DNS MX lookup → remote SMTP delivery
c. Architectural patterns & design principles:
– Plugin architecture (ZoneMTA’s hook system)
– Single responsibility (authentication, rewriting, upload, routing)
– Configuration-driven behavior via TOML
– External service integration (WildDuck, DNS, LMTP)
d. Key technologies & libraries:
– Node.js runtime
– ZoneMTA plugin API
– WildDuck HTTP/IMAP APIs
– LMTP protocol
– NPM packaging, Docker for deployment, GitHub Actions for CI

##### Diagramming conventions
– Green: internal modules (ZoneMTA, Plugin)
– Blue: external services (WildDuck, DNS, LMTP)
– Gray: configuration/CI tools

##### Key reminders
- Be exhaustive but not overly granular: capture all core data flows and integration points.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External SMTP Client
    SMTPClient["SMTP Client<br/>(Mail User Agent)"]:::external

    %% Internal Components
    subgraph "ZoneMTA SMTP Server" 
        direction TB
        ZoneMTA["ZoneMTA SMTP Interface<br/>(port 587)"]:::internal
        subgraph "zonemta-wildduck Plugin"
            direction TB
            PluginEntry["Plugin Entry Point<br/>(index.js)"]:::internal
            AuthStep["1. Authenticate User"]:::internal
            RewriteStep["2. Rewrite From Header"]:::internal
            UploadStep["3. Upload to Sent Mail (IMAP)"]:::internal
            RoutingStep["4. Decide Delivery Route"]:::internal
        end
    end

    %% External Services
    WildDuckAuth["WildDuck Authentication API"]:::service
    WildDuckIMAP["WildDuck IMAP Store"]:::service
    LMTPServer["Local LMTP Server"]:::service
    DNSMX["DNS MX Lookup"]:::service
    RemoteSMTP["Remote SMTP Delivery"]:::service

    %% Configuration Store
    Config["Configuration Store<br/>(config.example.toml)"]:::config

    %% CI/CD Pipeline
    subgraph "CI/CD & Build" 
        direction TB
        DockerfileNode["Dockerfile"]:::cicd
        Gruntfile["Gruntfile.js"]:::cicd
        WorkflowDocker[".github/workflows/docker-latest.yaml"]:::cicd
        WorkflowRelease[".github/workflows/release.yaml"]:::cicd
        WorkflowTest[".github/workflows/test.yml"]:::cicd
        Eslint[".eslintrc"]:::cicd
        Prettier[".prettierrc.js"]:::cicd
        Ncurc[".ncurc.js"]:::cicd
        PackageJSON["package.json"]:::cicd
        PackageLock["package-lock.json"]:::cicd
        Readme["README.md"]:::cicd
        Changelog["CHANGELOG.md"]:::cicd
        Licence["LICENCE"]:::cicd
        Gitignore[".gitignore"]:::cicd
        Npmrc[".npmrc"]:::cicd
    end

    %% Connections
    SMTPClient -->|SMTP| ZoneMTA
    ZoneMTA -->|hook: onConnect/onData| PluginEntry
    PluginEntry --> AuthStep
    AuthStep -->|HTTP/IMAP API| WildDuckAuth
    PluginEntry --> RewriteStep
    PluginEntry --> UploadStep
    UploadStep -->|IMAP APPEND| WildDuckIMAP
    PluginEntry --> RoutingStep
    RoutingStep -->|local domain?| LMTPServer
    RoutingStep -->|remote domain?| DNSMX
    DNSMX -->|MX records| RemoteSMTP

    %% Attach Config
    ZoneMTA --- Config
    PluginEntry --- Config

    %% Click Events
    click PluginEntry "https://github.com/zone-eu/zonemta-wildduck/blob/master/index.js"
    click Config "https://github.com/zone-eu/zonemta-wildduck/blob/master/config.example.toml"
    click PackageJSON "https://github.com/zone-eu/zonemta-wildduck/blob/master/package.json"
    click PackageLock "https://github.com/zone-eu/zonemta-wildduck/blob/master/package-lock.json"
    click WorkflowDocker "https://github.com/zone-eu/zonemta-wildduck/blob/master/.github/workflows/docker-latest.yaml"
    click WorkflowRelease "https://github.com/zone-eu/zonemta-wildduck/blob/master/.github/workflows/release.yaml"
    click WorkflowTest "https://github.com/zone-eu/zonemta-wildduck/blob/master/.github/workflows/test.yml"
    click DockerfileNode "https://github.com/zone-eu/zonemta-wildduck/tree/master/Dockerfile"
    click Gruntfile "https://github.com/zone-eu/zonemta-wildduck/blob/master/Gruntfile.js"
    click Eslint "https://github.com/zone-eu/zonemta-wildduck/blob/master/.eslintrc"
    click Prettier "https://github.com/zone-eu/zonemta-wildduck/blob/master/.prettierrc.js"
    click Ncurc "https://github.com/zone-eu/zonemta-wildduck/blob/master/.ncurc.js"
    click Readme "https://github.com/zone-eu/zonemta-wildduck/blob/master/README.md"
    click Changelog "https://github.com/zone-eu/zonemta-wildduck/blob/master/CHANGELOG.md"
    click Licence "https://github.com/zone-eu/zonemta-wildduck/tree/master/LICENCE"
    click Gitignore "https://github.com/zone-eu/zonemta-wildduck/blob/master/.gitignore"
    click Npmrc "https://github.com/zone-eu/zonemta-wildduck/blob/master/.npmrc"

    %% Styles
    classDef internal fill:#d2f8d2,stroke:#2b7a2b,color:#000
    classDef service fill:#d2e8ff,stroke:#1f4a8a,color:#000
    classDef config fill:#f0f0f0,stroke:#666,color:#000
    classDef cicd fill:#e0e0e0,stroke:#555,color:#000
    classDef external fill:#fff2cc,stroke:#b07700,color:#000
```
