# ankraft/smtpproxy architecture

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

- Interactive diagram: https://gitdiagram.com/ankraft/smtpproxy
- Repository: https://github.com/ankraft/smtpproxy

## Overview

##### Project type and purpose
- This is a single‐service SMTP Proxy Server written in Python (a network daemon).
- Purpose: accept SMTP connections from clients, queue messages locally, optionally perform POP-before-SMTP authentication, invoke extensible handlers, then relay mail to one or more remote SMTP servers.

##### File structure
Top-level files & directories:
- smtpproxy.py       – main entry point (starts listener, worker threads)
- smtps.py           – underlying threaded SMTP server implementation (imported/extended)
- config.py          – loads/parses smtpproxy.ini configuration
- MailHandler.py     – abstract base class for mail handlers
- handlers/          – plug-in modules (each implements a MailHandler subclass)
- mlogging.py        – central logging facility
- smtpproxy.ini.example / ini.d / service.example – configuration & service scripts
- msgs/ (created at runtime) – local mail queue (filesystem storage)

Architectural patterns & choices:
- Thread-per-connection for inbound SMTP (inherited from smtps.py)
- Producer/consumer model: listener threads produce saved message files; a relay thread consumes and forwards them.
- Plugin pattern: handlers loaded dynamically from handlers/ directory.
- Configuration-driven behavior (ini file)
- Logging via a rotating‐file logger

##### README for additional insights
- Confirms multi-threaded handling, POP-before-SMTP support, message queue directory, handler extension points, service installation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    SMTPClients["SMTP Clients"]:::external
    POP3Servers["POP3 Servers"]:::external
    RemoteSMTP["Remote SMTP Servers"]:::external

    %% SMTP Proxy Daemon
    subgraph "SMTP Proxy Daemon"
        Entry["smtpproxy.py\n(Main Entry)"]:::core
        Listener["smtps.py\nListener & Connection Handler"]:::core
        Relay["Relay Worker Thread"]:::core
        POPAuth["POP3 Authenticator"]:::core
        ConfigModule["config.py\nConfiguration Module"]:::infra
        IniExample["smtpproxy.ini.example"]:::infra
        Logging["mlogging.py\nLogging Module"]:::infra
        subgraph "Handlers"
            BaseHandler["MailHandler.py\nBase Class"]:::core
            subgraph "Plugins (handlers/)"
                Fix["FixAddress.py"]:::plugin
                Save["SaveNewPhoneMessage.py"]:::plugin
            end
        end
        MsgStore["msgs/\nMessage Store"]:::store
    end

    %% OS/Service Layer
    subgraph "OS Service Layer"
        InitScript["smtpproxy.init.d"]:::infra
        SystemdExample["smtpproxy.service.example"]:::infra
    end

    %% Connections
    SMTPClients -->|"SMTP Connection"| Listener
    Listener -->|"writes email"| MsgStore
    Listener -->|"handler hook"| BaseHandler
    BaseHandler -->|uses| Fix
    BaseHandler -->|uses| Save
    Relay -->|"polls"| MsgStore
    Relay -->|"if POP-before-SMTP"| POPAuth
    POPAuth -->|"auth"| POP3Servers
    Relay -->|"relay"| RemoteSMTP
    Listener -->|logs events| Logging
    Relay -->|logs events| Logging
    BaseHandler -->|logs events| Logging
    IniExample -->|loaded by| ConfigModule
    ConfigModule -->|configures| Entry
    Entry -->|starts| Listener
    Entry -->|starts| Relay
    InitScript -->|launches| Entry
    SystemdExample -->|launches| Entry

    %% Click Events
    click Entry "https://github.com/ankraft/smtpproxy/blob/master/smtpproxy.py"
    click Listener "https://github.com/ankraft/smtpproxy/blob/master/smtps.py"
    click ConfigModule "https://github.com/ankraft/smtpproxy/blob/master/config.py"
    click IniExample "https://github.com/ankraft/smtpproxy/blob/master/smtpproxy.ini.example"
    click BaseHandler "https://github.com/ankraft/smtpproxy/blob/master/MailHandler.py"
    click Fix "https://github.com/ankraft/smtpproxy/blob/master/handlers/FixAddress.py"
    click Save "https://github.com/ankraft/smtpproxy/blob/master/handlers/SaveNewPhoneMessage.py"
    click Plugins "https://github.com/ankraft/smtpproxy/tree/master/handlers/"
    click Logging "https://github.com/ankraft/smtpproxy/blob/master/mlogging.py"
    click InitScript "https://github.com/ankraft/smtpproxy/blob/master/smtpproxy.init.d"
    click SystemdExample "https://github.com/ankraft/smtpproxy/blob/master/smtpproxy.service.example"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef plugin fill:#98FB98,stroke:#000,stroke-width:1px
    classDef store fill:#EFEFEF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
