# mkitchingh/smtp-relay architecture

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

- Interactive diagram: https://gitdiagram.com/mkitchingh/smtp-relay
- Repository: https://github.com/mkitchingh/smtp-relay

## Overview

Windows SMTP relay service with an administrator-facing configuration GUI. The main workflow is an SMTP client submitting mail to the service, which checks relay access, parses the message, and relays it to the configured upstream host; the service returns an SMTP result. Configuration, service control, and privacy-conscious logging are supporting capabilities. Edges reflect the excerpts, source index, and README; unsampled implementation details are not inferred.

Main entry points: [`src/SmtpRelay/Program.cs`](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Program.cs) (Service Host), [`src/SmtpRelay/Worker.cs`](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Worker.cs) (Listener Worker), [`src/SmtpRelay/MessageRelayStore.cs`](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/MessageRelayStore.cs) (Relay Handler), [`src/SmtpRelay/Config.cs`](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Config.cs) (Relay Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration UI"]
  node_gui["Configuration GUI<br/>[MainForm.cs]"]
  node_config["Relay Configuration<br/>[Config.cs]"]
end

subgraph group_service["Relay Service"]
  node_service_host["Service Host<br/>[Program.cs]"]
  node_worker["Listener Worker<br/>[Worker.cs]"]
  node_smtp_server["SMTP Listener<br/>[Worker.cs]"]
end

subgraph group_delivery["Mail Delivery"]
  node_relay_store["Relay Handler"]
  node_access_check["Relay Access Check"]
  node_message_parse["Message Parsing"]
  node_smtp_delivery["SMTP Delivery"]
end

subgraph group_observability["Logging"]
  node_protocol_log["Redacted Protocol Log"]
  node_app_log["Application Logging<br/>[SmtpLogger.cs]"]
  node_log_config["Logging Settings<br/>[Logging.cs]"]
end

node_admin(("Administrator"))
node_smtp_clients(("SMTP Clients"))
node_upstream(("Upstream SMTP Host"))

node_admin -->|"configures"| node_gui
node_gui -->|"loads settings"| node_config
node_gui -->|"restarts service"| node_service_host
node_service_host -->|"loads config"| node_config
node_service_host -->|"initializes"| node_app_log
node_service_host -->|"registers"| node_worker
node_worker -->|"loads config"| node_config
node_worker -->|"initializes"| node_app_log
node_worker -->|"starts"| node_smtp_server
node_worker -->|"registers handler"| node_relay_store
node_smtp_clients -.->|"submits mail"| node_smtp_server
node_smtp_server -.->|"dispatches message"| node_relay_store
node_relay_store -->|"checks sender"| node_access_check
node_relay_store -->|"parses message"| node_message_parse
node_relay_store -->|"relays message"| node_smtp_delivery
node_smtp_delivery -->|"connects and sends"| node_upstream
node_smtp_delivery -->|"logs session"| node_protocol_log
node_smtp_delivery -->|"uses relay settings"| node_config
node_service_host -->|"configures logging"| node_log_config
node_app_log -->|"uses retention settings"| node_log_config

click node_gui "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay.GUI/MainForm.cs"
click node_config "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Config.cs"
click node_service_host "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Program.cs"
click node_worker "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Worker.cs"
click node_smtp_server "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Worker.cs"
click node_relay_store "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/MessageRelayStore.cs"
click node_access_check "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/MessageRelayStore.cs"
click node_message_parse "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/MessageRelayStore.cs"
click node_smtp_delivery "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/MessageRelayStore.cs"
click node_protocol_log "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/RedactingSmtpProtocolLogger.cs"
click node_app_log "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/SmtpLogger.cs"
click node_log_config "https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Logging.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gui,node_config,node_smtp_clients toneBlue
class node_service_host,node_worker,node_smtp_server toneAmber
class node_relay_store,node_access_check,node_message_parse,node_smtp_delivery toneMint
class node_protocol_log,node_app_log,node_log_config toneRose
class node_admin,node_upstream toneIndigo
```

## Components

### Configuration UI

- [Configuration GUI](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay.GUI/MainForm.cs): `src/SmtpRelay.GUI/MainForm.cs`
- [Relay Configuration](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Config.cs): `src/SmtpRelay/Config.cs`

### Relay Service

- [Service Host](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Program.cs): `src/SmtpRelay/Program.cs`
- [Listener Worker](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Worker.cs): `src/SmtpRelay/Worker.cs`
- [SMTP Listener](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Worker.cs): `src/SmtpRelay/Worker.cs`

### Mail Delivery

- [Relay Handler](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/MessageRelayStore.cs): `src/SmtpRelay/MessageRelayStore.cs`
- [Relay Access Check](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/MessageRelayStore.cs): `src/SmtpRelay/MessageRelayStore.cs`
- [Message Parsing](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/MessageRelayStore.cs): `src/SmtpRelay/MessageRelayStore.cs`
- [SMTP Delivery](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/MessageRelayStore.cs): `src/SmtpRelay/MessageRelayStore.cs`

### Logging

- [Redacted Protocol Log](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/RedactingSmtpProtocolLogger.cs): `src/SmtpRelay/RedactingSmtpProtocolLogger.cs`
- [Application Logging](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/SmtpLogger.cs): `src/SmtpRelay/SmtpLogger.cs`
- [Logging Settings](https://github.com/mkitchingh/smtp-relay/blob/main/src/SmtpRelay/Logging.cs): `src/SmtpRelay/Logging.cs`

### Other components

- **Administrator**
- **SMTP Clients**
- **Upstream SMTP Host**

## Connections

- Administrator → Configuration GUI: configures (evidence: `README.md`)
- Configuration GUI → Relay Configuration: loads settings (evidence: `src/SmtpRelay.GUI/MainForm.cs`)
- Configuration GUI → Service Host: restarts service (evidence: `src/SmtpRelay.GUI/MainForm.cs`)
- Service Host → Relay Configuration: loads config (evidence: `src/SmtpRelay/Program.cs`)
- Service Host → Application Logging: initializes (evidence: `src/SmtpRelay/Program.cs`)
- Service Host → Listener Worker: registers (evidence: `src/SmtpRelay/Program.cs`)
- Listener Worker → Relay Configuration: loads config (evidence: `src/SmtpRelay/Worker.cs`)
- Listener Worker → Application Logging: initializes (evidence: `src/SmtpRelay/Worker.cs`)
- Listener Worker → SMTP Listener: starts (evidence: `src/SmtpRelay/Worker.cs`)
- Listener Worker → Relay Handler: registers handler (evidence: `src/SmtpRelay/Worker.cs`)
- SMTP Clients → SMTP Listener: submits mail
- SMTP Listener → Relay Handler: dispatches message (evidence: `src/SmtpRelay/Worker.cs`)
- Relay Handler → Relay Access Check: checks sender (evidence: `src/SmtpRelay/MessageRelayStore.cs`)
- Relay Handler → Message Parsing: parses message (evidence: `src/SmtpRelay/MessageRelayStore.cs`)
- Relay Handler → SMTP Delivery: relays message (evidence: `src/SmtpRelay/MessageRelayStore.cs`)
- SMTP Delivery → Upstream SMTP Host: connects and sends (evidence: `src/SmtpRelay/MessageRelayStore.cs`)
- SMTP Delivery → Redacted Protocol Log: logs session (evidence: `src/SmtpRelay/MessageRelayStore.cs`)
- SMTP Delivery → Relay Configuration: uses relay settings (evidence: `src/SmtpRelay/MessageRelayStore.cs`)
- Service Host → Logging Settings: configures logging
- Application Logging → Logging Settings: uses retention settings (evidence: `src/SmtpRelay/SmtpLogger.cs`)
