# rnwood/smtp4dev architecture

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

- Interactive diagram: https://gitdiagram.com/rnwood/smtp4dev
- Repository: https://github.com/rnwood/smtp4dev

## Overview

##### Project type and purpose
- This is a full-stack development and testing tool (“smtp4dev”) that provides:
- A fake SMTP server (SMTP listener, relay, session logging)
- IMAP access to retrieve/delete messages
- A REST API (OpenAPI/Swagger)
- A real-time Web UI (Vue.js + SignalR)
- A cross-platform desktop wrapper (Electron/.NET) and CLI

##### File structure
- Top-level solutions:
- smtp4dev.sln (core server + API + UI + Desktop + tests)
- imapserver and smtpserver libraries (protocol stacks used by smtp4dev)
- Key directories under Rnwood.Smtp4dev:
- Controllers (ASP.NET Core REST controllers)
- Hubs (SignalR notification hub)
- Server (SMTP/IMAP listener implementations, cert generation, relay)
- Data (EF Core DbContext + repository)
- ClientApp (Vue.js single-page application served by ASP.NET Core)
- Desktop (wrapper app launching the SPA + embedded server)
- Tests (unit, E2E, desktop launch)
- Configuration/build/deployment:
- Dockerfiles (Windows/Linux/ARM) + docker-compose.yml
- .NET launchSettings, appsettings.json, web.config

##### README for additional insights
- Lists features: SMTP, IMAP, Web UI, API, TLS, scripting rules, multiple mailboxes

##### Main components & their relationships
a. Components:
1. SMTP4dev Server Host (ASP.NET Core process)
- SMTP Listener (listens on SMTP port, uses smtpserver library)
- IMAP Listener (IMAP port, uses imapserver library)
- REST API Controllers (Swagger/OpenAPI endpoints)
- SignalR NotificationsHub (real-time updates pushed to UI)
- Data Layer (EF Core DbContext → SQLite or in-memory)
- Scripting and relay engine (applies user rules)
2. Data Store
- Messages, sessions, mailboxes, relay errors persisted via EF Migrations
3. Web UI (Vue.js SPA)
- Served by ASP.NET Core via static files
- Connects to REST API over HTTP and to NotificationsHub over WebSockets
4. Desktop App
- Hosts the server and SPA, bundles into a native desktop executable
5. CLI
- Provides command-line interface to start/stop the server, run scripts
6. External SMTP/IMAP Clients
- Developer applications sending to SMTP port
- IMAP clients retrieving from mailbox

b. Interactions (data flows):
1. SMTP client → SMTP Listener → Data Layer → NotificationsHub → Web UI
2. Web UI ↔ REST API Controllers → Data Layer
3. Web UI ↔ SignalR Hub → Real-time message/session events
4. IMAP client → IMAP Listener → Data Layer
5. Desktop/CLI → Hosts the above server components

c. Architectural patterns and principles
- Layered architecture: Presentation (Vue SPA), API (Controllers), Domain/Server, Data
- Real-time push via SignalR Hubs
- EF Core Code-First migrations
- Modular protocol implementations via separate libraries (imapserver, smtpserver)
- Dependency injection throughout ASP.NET Core
- Cross-platform hosting via Docker and .NET Core

d. Key technologies/frameworks
- ASP.NET Core Web API
- Entity Framework Core
- SignalR (NotificationsHub)
- Vue.js + Vite
- Docker (containers for Linux/Windows)
- Electron/.NET Desktop host
- imapserver & smtpserver open-source stacks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    DevSMTP["Developer SMTP Client"]:::external
    IMAPClient["IMAP Client"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        VueSPA["Vue.js SPA"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        SMTPListener["SMTP Listener"]:::backend
        IMAPListener["IMAP Listener"]:::backend
        Controllers["REST API Controllers"]:::backend
        NotificationsHub["SignalR NotificationsHub"]:::backend
        ScriptingRelay["Scripting & Relay Engine"]:::backend
        CertTLS["Certificate & TLS Helpers"]:::backend
        ServerSettings["Server Settings & Options"]:::backend
        DataLayer["Data Layer (EF Core DbContext & Repo)"]:::backend
        EFMigrations["EF Migrations"]:::backend
        Startup["App Startup & Hosting"]:::backend
    end

    %% Hosts
    DesktopApp["Desktop App"]:::backend
    CLI["Command-Line Interface (CLI)"]:::backend

    %% Data Store
    DataStore[(Data Store)]:::database

    %% Docker
    Docker["Docker / Containers"]:::external

    %% Connections
    DevSMTP -->|sends email| SMTPListener
    IMAPClient -->|retrieves email| IMAPListener

    SMTPListener -->|stores message| DataLayer
    IMAPListener -->|stores session| DataLayer
    Controllers -->|CRUD over HTTP| DataLayer
    VueSPA -->|HTTP REST API| Controllers
    VueSPA -->|WebSocket| NotificationsHub
    NotificationsHub -->|push events| VueSPA
    ScriptingRelay -->|process rules| SMTPListener
    CertTLS -->|generate certs| SMTPListener
    ServerSettings -->|configure| SMTPListener
    ServerSettings -->|configure| IMAPListener
    DataLayer -->|migrations| EFMigrations
    DataLayer -->|persist to| DataStore
    Startup -->|boot| SMTPListener
    Startup -->|boot| IMAPListener
    Startup -->|boot| Controllers
    Startup -->|boot| NotificationsHub
    DesktopApp -->|hosts| Startup
    CLI -->|hosts| Startup
    DesktopApp -.-> Docker
    CLI -.-> Docker

    %% Click Events
    click SMTPListener "https://github.com/rnwood/smtp4dev/blob/master/Rnwood.Smtp4dev/Server/Smtp4devServer.cs"
    click IMAPListener "https://github.com/rnwood/smtp4dev/blob/master/Rnwood.Smtp4dev/Server/Imap/ImapServer.cs"
    click Controllers "https://github.com/rnwood/smtp4dev/tree/master/Rnwood.Smtp4dev/Controllers"
    click NotificationsHub "https://github.com/rnwood/smtp4dev/blob/master/Rnwood.Smtp4dev/Hubs/NotificationsHub.cs"
    click DataLayer "https://github.com/rnwood/smtp4dev/blob/master/Rnwood.Smtp4dev/Data/Smtp4devDbContext.cs"
    click EFMigrations "https://github.com/rnwood/smtp4dev/tree/master/Rnwood.Smtp4dev/Migrations"
    click ScriptingRelay "https://github.com/rnwood/smtp4dev/blob/master/Rnwood.Smtp4dev/Server/ScriptingHost.cs"
    click CertTLS "https://github.com/rnwood/smtp4dev/blob/master/Rnwood.Smtp4dev/Server/CertificateHelper.cs"
    click ServerSettings "https://github.com/rnwood/smtp4dev/tree/master/Rnwood.Smtp4dev/Server/Settings"
    click VueSPA "https://github.com/rnwood/smtp4dev/tree/master/Rnwood.Smtp4dev/ClientApp"
    click DesktopApp "https://github.com/rnwood/smtp4dev/blob/master/Rnwood.Smtp4dev.Desktop"
    click CLI "https://github.com/rnwood/smtp4dev/blob/master/Rnwood.Smtp4dev/CommandLineParser.cs"
    click Startup "https://github.com/rnwood/smtp4dev/blob/master/Rnwood.Smtp4dev/Startup.cs"

    %% Styles
    classDef backend fill:#cfc,stroke:#060,stroke-width:2px
    classDef frontend fill:#ccf,stroke:#06c,stroke-width:2px
    classDef external fill:#fc9,stroke:#c60,stroke-width:2px
    classDef database fill:#ff9,stroke:#aa0,stroke-width:2px
```
