# matrixise/dsmtpd architecture

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

- Interactive diagram: https://gitdiagram.com/matrixise/dsmtpd
- Repository: https://github.com/matrixise/dsmtpd

## Overview

##### Project type and purpose
- Type: CLI network service (a lightweight SMTP debug server written in Python).
- Purpose: Provide developers with a throwaway SMTP endpoint for testing, optionally persisting incoming messages to a Maildir.

##### File structure for architectural cues
- Top-level files: setup.py, pyproject.toml, Makefile (packaging & build).
- “dsmtpd/” package:
–  __main__.py: CLI entry point that invokes the server.
–  _dsmtpd.py: core SMTP server logic (listener, handler).
- “tests/”: unit tests for CLI and core logic.
- No split “frontend/backend” – it’s a single process, network-centric tool.

##### Read README for additional insights
- CLI flags:
-p (port), -i (interface), -d (Maildir directory).
- Behavior:
–  Launch SMTP server at given socket.
–  Incoming mail either logged to console or saved to Maildir subfolders (tmp, new, cur).
–  Uses explicit exit codes for success/failure (0 or 2).

##### Main components
a. CLI Front End
–  Parses user args (port, interface, Maildir path).
–  Instantiates the SMTP server.
b. Async Event Loop (Python’s asyncore or asyncio reactor pattern)
–  Accepts and demultiplexes connections.
c. SMTP Server Socket & Protocol Handler
–  Listens on a TCP socket.
–  Implements SMTP handshake, MAIL/RCPT/DATA commands.
d. Message Dispatcher / Handler
–  Receives complete messages.
–  Routes to storage or logger.
e. Storage Subsystem
–  If “-d” provided: validates Maildir (tmp, new, cur) → writes files.
–  Else: logs content to STDOUT or file via Python logging module.
f. Exit / Cleanup
–  Handles signals (e.g., SIGINT) → clean shutdown → exit code 0.
–  On invalid Maildir: immediate exit code 2.

##### Relationships and data flows
- CLI → (args) → Server constructor.
- Reactor → (socket events) → Protocol Handler.
- Protocol Handler → (parsed email) → Dispatcher → Storage or Logger.
- File System (Maildir) ← Storage writes new message files.
- Logging component ← all major events.

##### Key architectural patterns & technologies
- Reactor/Event-loop for networking (asyncore or asyncio).
- Python’s built-in smtpd.SMTPServer subclass or custom handler.
- Maildir standard directory layout.
- Click or argparse for CLI (if used).
- Standard logging module.

##### Putting it all together
- Dispatcher forks two paths:
1. → “Maildir Writer” → writes to Maildir FS
2. → “Logger” → STDOUT/Log file
- “Signal Handler” hooking into Event Loop for clean shutdown.
- Optional note: Unit tests in tests/ validate CLI and handler behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    User["User"]:::external
    CLI[/CLI Parser/]:::io
    Init["Server Init"]:::runtime
    Loop["Async Event Loop"]:::runtime
    SMTP["SMTP Protocol Handler"]:::runtime
    Disp["Message Dispatcher"]:::runtime
    Writer["Maildir Writer"]:::runtime
    Logger[/Logger/]:::io
    FS[(Maildir FS)]:::datastore
    Signal["Signal Handler"]:::runtime

    subgraph "Tests"
        TCli["CLI Tests"]:::external
        TCore["Core Logic Tests"]:::external
    end

    %% Data Flows
    User -->|"run dsmtpd CLI"| CLI
    CLI -->|"args"| Init
    Init --> Loop
    Loop -->|"socket events"| SMTP
    SMTP -->|"parsed email"| Disp
    Disp -->|"write message file"| Writer
    Writer -->|"store file"| FS
    Disp -->|"log message"| Logger
    Signal -.->|"signal shutdown"| Loop

    %% Click Events
    click CLI "https://github.com/matrixise/dsmtpd/blob/main/dsmtpd/__main__.py"
    click Init "https://github.com/matrixise/dsmtpd/blob/main/dsmtpd/_dsmtpd.py"
    click SMTP "https://github.com/matrixise/dsmtpd/blob/main/dsmtpd/_dsmtpd.py"
    click Disp "https://github.com/matrixise/dsmtpd/blob/main/dsmtpd/_dsmtpd.py"
    click Writer "https://github.com/matrixise/dsmtpd/blob/main/dsmtpd/_dsmtpd.py"
    click Logger "https://github.com/matrixise/dsmtpd/blob/main/dsmtpd/_dsmtpd.py"
    click TCli "https://github.com/matrixise/dsmtpd/blob/main/tests/test_cli.py"
    click TCore "https://github.com/matrixise/dsmtpd/blob/main/tests/test_dsmtpd.py"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef runtime fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#333,stroke-width:1px
    classDef io fill:#D3D3D3,stroke:#333,stroke-width:1px
```
