# modalsource/postal architecture

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

- Interactive diagram: https://gitdiagram.com/modalsource/postal
- Repository: https://github.com/modalsource/postal

## Overview

##### Project type and purpose
- Postal is a self-hosted, open-source mail server (like SendGrid/Mailgun) built on Ruby on Rails.
- It provides a web-based admin UI, HTTP/SMTP APIs for sending and receiving mail, background workers, message storage, spam inspection, webhooks, MTA-STS/TLS-RPT support, and health/metrics endpoints.

##### Main components
a. Web Application (Rails MVC)
- app/controllers + app/views + app/assets → HTML UI & REST/legacy JSON API
- config/routes.rb → maps HTTP(S) endpoints
b. Primary Configuration Database
- ActiveRecord models (app/models) + config/database.yml → stores users, domains, credentials, routes, settings
c. SMTP Ingress Server
- lib/smtp_server → listens on port 25/587, accepts incoming mail, enqueues messages
d. Message Dequeuer & Processor
- app/lib/message_dequeuer pipeline → pulls queued messages, runs spam checks, applies routing, writes to message store
e. Message Database (Message DB)
- lib/postal/message_db → separate optimized store for message bodies, deliveries, stats, webhooks
f. SMTP Egress Client / Sender
- lib/smtp_client & app/senders → delivers outgoing mail to external SMTP servers
g. Background Workers & Scheduled Tasks
- app/lib/worker/jobs + app/scheduled_tasks → retention, DNS checks, webhook retries, notification jobs
h. Webhook Delivery Service
- app/services/webhook_delivery_service → posts events to customer-configured HTTP endpoints
i. Spam Inspection Modules
- lib/postal/message_inspectors → integrators for ClamAV, SpamAssassin, Rspamd, Truemail
j. DNS Resolver & MTA-STS/TLS-RPT Endpoints
- lib/dns_resolver + app/controllers/mta_sts_controller → publishes TXT/HTTPS policies
k. Health & Metrics
- app/util/health_server → Prometheus-style metrics endpoint
l. CLI & Scripts
- bin/*, script/* → tooling for setup, migration, signing, testing

##### Relationships & data flows
- Browser/API client → HTTPS → Rails Web App → Primary DB (config, UI state).
- Incoming SMTP → SMTP Server → QueuedMessage (Primary DB) → Message Dequeuer →
- Spam inspectors → Message DB → Webhook queue or routing decision.
- Outgoing Submission (HTTP API/Web UI) → OutgoingMessagePrototype → Worker picks up → SMTP Client → external SMTP servers → Message DB for logging.
- Scheduled tasks (cron or Clock process) → invoke ScheduledTask classes → maintenance jobs (cleanup, DNS checks, stats).
- WebhookDeliveryService → polls Message DB for events → HTTP POST to external webhooks.
- Health Server runs alongside Workers → exposes /health and /metrics.

##### Architectural patterns & design principles
- MVC for the management console and HTTP APIs
- Asynchronous, event-driven processing for mail pipelines
- Separation of concerns: config/state in Primary DB vs high-volume message data in Message DB
- Modular “inspector” and “sender” plugins for extensibility
- Scheduled tasks for periodic maintenance
- Clear boundary between sync (UI/API) and async (workers)

##### Showing interactions
- Cron or scheduler triggers on scheduled tasks.

##### Essential details to capture
- Dual-database architecture (config vs message store)
- Dual API: Legacy JSON API vs RESTful API vs Web UI
- SMTP ingress vs egress pipelines
- Spam inspection and webhook delivery as modular services
- Scheduled tasks separate from real-time processing
- Health/metrics endpoint for Prometheus
- Deployment artifacts: Docker containers, Procfile.dev, Puma config

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Tier 1: Clients
    subgraph "Tier 1: Clients"
        Browser((Browser)):::external
        APIClient((API Client)):::external
        SMTPPeer((SMTP Peer)):::external
    end

    %% Tier 2: Rails Web App
    subgraph "Tier 2: Rails Web App"
        Controllers["Controllers"]:::webuiapi
        Views["Views"]:::webuiapi
        Assets["Assets"]:::webuiapi
        Routes["config/routes.rb"]:::webuiapi
    end

    %% Tier 3: Message Pipeline
    subgraph "Tier 3: Message Pipeline"
        SMTPIngress["SMTP Ingress Server"]:::async
        Dequeuer["Message Dequeuer & Processor"]:::async
        Inspectors["Spam Inspection Modules"]:::async
        Egress["SMTP Egress Client / Sender"]:::async
    end

    %% Tier 4: Workers & Scheduled Tasks
    subgraph "Tier 4: Workers & Scheduled Tasks"
        Workers["Background Workers"]:::async
        Scheduler["Scheduled Tasks"]:::async
        WebhookService["Webhook Delivery Service"]:::async
    end

    %% Tier 5: Data Stores
    subgraph "Tier 5: Data Stores"
        PrimaryDB[(Primary DB)]:::db
        MessageDB[(Message DB)]:::db
    end

    %% Tier 6: External Services
    subgraph "Tier 6: External Services"
        DNS["DNS & MTA-STS/TLS-RPT"]:::external
        SpamEngines["Spam Engines\n(ClamAV/SpamAssassin/Rspamd/Truemail)"]:::external
        ExternalSMTP["External SMTP Servers"]:::external
        WebhookEP["Customer Webhook Endpoints"]:::external
    end

    %% Connections - synchronous
    Browser -->|HTTPS| Controllers
    APIClient -->|HTTPS| Controllers
    Controllers -->|ActiveRecord| PrimaryDB
    Controllers -->|renders| Views
    Controllers -->|serves assets| Assets
    Controllers -->|routes| Routes

    %% SMTP ingress
    SMTPPeer -->|SMTP 25/587| SMTPIngress
    SMTPIngress -->|queues QueuedMessage| Dequeuer

    %% Dequeuer pipeline
    Dequeuer -->|runs inspectors| Inspectors
    Inspectors -->|stores body & stats| MessageDB
    Dequeuer -->|applies routing| Workers
    Workers -->|writes config| PrimaryDB

    %% Outgoing submission
    Controllers -->|creates OutgoingMessagePrototype| Workers
    Workers -->|job: process_queued_messages| Dequeuer
    Egress -->|SMTP deliver| ExternalSMTP
    Egress -->|logs DeliveryRecord| MessageDB

    %% Scheduled tasks and webhooks
    Scheduler -->|cron triggers| Workers
    WebhookService -->|polls events| MessageDB
    WebhookService -->|HTTP POST| WebhookEP

    %% DNS and health
    DNS -->|policy TXT/HTTPS| Controllers
    Controllers -->|fetch resolver| DNS

    %% Metrics
    Controllers -->|/health & /metrics| MessageDB
    Workers -->|exposes| MessageDB

    %% Styles
    classDef webuiapi fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef async fill:#FFE8C0,stroke:#D47A00,color:#D47A00;
    classDef db fill:#E0F7E0,stroke:#1E8C1E,color:#1E8C1E;
    classDef external fill:#F0F0F0,stroke:#888888,color:#555555;

    %% Click Events
    click Controllers "https://github.com/modalsource/postal/tree/main-modalsource/app/controllers"
    click Views "https://github.com/modalsource/postal/tree/main-modalsource/app/views"
    click Assets "https://github.com/modalsource/postal/tree/main-modalsource/app/assets"
    click Routes "https://github.com/modalsource/postal/blob/main-modalsource/config/routes.rb"
    click PrimaryDB "https://github.com/modalsource/postal/tree/main-modalsource/app/models"
    click PrimaryDB "https://github.com/modalsource/postal/blob/main-modalsource/config/database.yml"
    click SMTPIngress "https://github.com/modalsource/postal/tree/main-modalsource/lib/smtp_server"
    click Dequeuer "https://github.com/modalsource/postal/blob/main-modalsource/app/lib/message_dequeuer.rb"
    click Inspectors "https://github.com/modalsource/postal/tree/main-modalsource/lib/postal/message_inspectors"
    click MessageDB "https://github.com/modalsource/postal/tree/main-modalsource/lib/postal/message_db"
    click Egress "https://github.com/modalsource/postal/tree/main-modalsource/lib/smtp_client"
    click Egress "https://github.com/modalsource/postal/tree/main-modalsource/app/senders"
    click Workers "https://github.com/modalsource/postal/tree/main-modalsource/app/lib/worker/jobs"
    click Scheduler "https://github.com/modalsource/postal/tree/main-modalsource/app/scheduled_tasks"
    click WebhookService "https://github.com/modalsource/postal/blob/main-modalsource/app/services/webhook_delivery_service.rb"
    click DNS "https://github.com/modalsource/postal/blob/main-modalsource/app/lib/dns_resolver.rb"
    click DNS "https://github.com/modalsource/postal/blob/main-modalsource/app/controllers/mta_sts_controller.rb"
    click MessageDB "https://github.com/modalsource/postal/blob/main-modalsource/app/util/health_server.rb"
    click MessageDB "https://github.com/modalsource/postal/blob/main-modalsource/app/util/has_prometheus_metrics.rb"
    click CLI "https://github.com/modalsource/postal/tree/main-modalsource/bin"
    click CLI "https://github.com/modalsource/postal/tree/main-modalsource/script"
    class CLI external
```
