# changemakerstudios/papercut-smtp architecture

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

- Interactive diagram: https://gitdiagram.com/changemakerstudios/papercut-smtp
- Repository: https://github.com/changemakerstudios/papercut-smtp

## Overview

##### Project Type and Purpose
- This is “Papercut SMTP,” a .NET-based full-stack application that combines:
- An embedded SMTP server (development-only mail sink)
- A domain-driven backend (message storage, rules engine, message bus)
- A desktop front end (WPF/UI) plus an HTML/JS UI hosted in‐process or via Electron
- An optional HTTP/REST service with Web UI and Docker support

##### High-Level File-Structure Analysis
- Top‐Level Solution (Papercut.sln)
- build/*, Dockerfile, Cake scripts for CI/CD
- chocolatey/ and extras/ for packaging & install scripts
- src/Common, Core, Message, Rules, Infrastructure.* – Core libraries
- Domain model (IMessage, ICommand, IEvent, Rules, Paths, Settings)
- Infrastructure (Async, Logging, JSON, MessageBus, Container modules)
- src/Infrastructure.IPComm & Infrastructure.Smtp – pluggable network protocols
- src/Service – NUnit-hosted SMTP service + ASP.NET Core HTTP API + static Web assets + SignalR hub
- src/UI – WPF desktop application (MVVM + Autofac DI + WebView2 for HTML UI)
- test/ – Web API integration tests

##### README Insights
- Primary use case: capture outgoing development emails safely
- Features: SMTP listener on port 25, instant notifications, full MIME inspection, optional HTTP service on port 80/8080

a. Main Components to Model
1. SMTP Listener
- Papercut.Core’s SMTP server implementation (Papercut.Infrastructure.Smtp)
2. Domain & Business Logic
- Papercut.Core (Domain + Infrastructure modules)
- Rules Engine (Papercut.Rules)
- Message Repository (Papercut.Message)
3. Message Bus
- AutofacMessageBus (publish/subscribe events internally)
4. Persistence / Storage
- File-system based JSON store (JsonSettingStore + message files under configured paths)
5. Backend Service Host
- ASP.NET Core WebHost (Controllers, Static Content, SignalR NewMessagesHub)
- In-process HTTP server for desktop standalone mode
6. Desktop UI
- WPF MVVM app (Papercut.UI)
- WebView2 or Electron host loading HTML/JS SPA
- IPComm channel for event & command exchange between UI and service
7. External Interfaces
- SMTP protocol ingress (port 25)
- HTTP/REST ingress (port 80/8080)
- IPComm (custom TCP loopback channel)

b. Relationships & Data Flows
1. SMTP Client → SMTP Listener
2. Listener publishes NewMessageEvent on MessageBus
3. RulesRunner consumes events, applies Rules, writes Message files
4. MessageRepository reads stored messages
5. HTTP Controllers and SignalR Hub expose messages & notifications
6. Desktop UI connects via IPComm or HTTP/SignalR to receive NewMessage notifications and query messages
7. WPF view models bind to HTML/JS UI via WebView2 or native controls

c. Architectural Patterns & Principles
- Layered Architecture (Domain / Infrastructure / Service / UI)
- Dependency Injection with Autofac modules (PapercutCoreModule, PapercutMessageModule, etc.)
- Publish/Subscribe MessageBus for decoupling components
- Modular design via separate projects & NuGet packaging (Common, Core, Infrastructure, Message, Rules, UI, Service)
- In-Process hosting for desktop convenience, plus optional Dockerized container for headless service

d. Key Technologies & Frameworks
- .NET (Framework & .NET Core)
- Autofac (DI)
- Cake & PowerShell (build automation)
- WPF + MVVM (Papercut.UI)
- WebView2 / Electron (HTML/JS UI)
- ASP.NET Core MVC & SignalR (Papercut.Service Web API)
- Custom IPComm protocol (loopback socket for UI ↔ service coordination)
- File-system JSON storage (message + settings persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Network Edge"
        direction TB
        ExtSMTP[/"SMTP Client"/]:::external
        ExtHTTP[/"HTTP Client"/]:::external
        SMTPListener["SMTP Listener\n(port 25)"]:::network
        HTTPEndpoint["HTTP Ingress\n(port 80/8080)"]:::network
        SmtpModule["SMTP DI Module"]:::infra
    end

    ExtSMTP -->|SMTP| SMTPListener
    ExtHTTP -->|HTTP/REST| HTTPEndpoint
    SmtpModule --> SMTPListener

    subgraph "Core Processing"
        direction TB
        Domain["Core Domain"]:::core
        Infrastructure["Core Infrastructure"]:::infra
        MsgBus["MessageBus\nAutofacMessageBus"]:::infra
        RulesDomain["Rules Domain"]:::core
        RulesRunner["RulesRunner"]:::infra
        RuleModule["Rules DI Module"]:::infra
        MessageRepo["Message Repository"]:::core
        SmtpStore["SMTP Message Store"]:::infra
        Settings["Settings Store\n(JsonSettingStore)"]:::infra
    end

    SMTPListener -->|NewMessageEvent| MsgBus
    MsgBus -->|publish| RulesRunner
    RulesRunner -->|uses| RulesDomain
    RulesRunner -->|writes| SmtpStore
    MessageRepo -->|reads| SmtpStore
    Settings --> Infrastructure
    Infrastructure --> Domain

    subgraph "Service Layer"
        direction TB
        ApiHost["HTTP API Host"]:::service
        Controllers["Controllers"]:::service
        SignalR["SignalR Hub"]:::service
        StaticAssets["Web UI Assets"]:::infra
        InProcHost["In-Process HTTP Server"]:::service
        Electron["Electron Shell"]:::service
    end

    HTTPEndpoint -->|requests| ApiHost
    ApiHost --> Controllers
    ApiHost --> SignalR
    ApiHost --> StaticAssets
    InProcHost --> Controllers
    Electron --> ApiHost

    subgraph "UI Layer"
        direction TB
        WPF["WPF Desktop UI"]:::ui
        WebUI["HTML/JS UI\n(WebView2/Electron)"]:::ui
        IPCommProto["IPComm Protocol"]:::network
        UIModule["UI DI Module"]:::infra
    end

    WPF -->|Commands/Events| IPCommProto
    WebUI -->|HTTP/SignalR| ApiHost
    IPCommProto -->|loopback| ApiHost
    SignalR --> WebUI
    SignalR --> WPF

    classDef core fill:#C3DDF9,stroke:#0366D6,color:#0366D6
    classDef network fill:#DFFFE0,stroke:#228B22,color:#228B22
    classDef infrap fill:#F0F0F0,stroke:#666666,color:#333333
    classDef infra fill:#F0F0F0,stroke:#666666,color:#333333
    classDef service fill:#FFF4E5,stroke:#E67E22,color:#E67E22
    classDef ui fill:#FFEED5,stroke:#D35400,color:#D35400
    classDef external fill:#FFFFFF,stroke:#AAAAAA,color:#666666

    click SMTPListener "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Infrastructure.Smtp/PapercutSmtpServer.cs"
    click SmtpModule "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Infrastructure.Smtp/PapercutSmtpModule.cs"
    click Domain "https://github.com/changemakerstudios/papercut-smtp/tree/develop/src/Papercut.Core/Domain"
    click Infrastructure "https://github.com/changemakerstudios/papercut-smtp/tree/develop/src/Papercut.Core/Infrastructure"
    click MsgBus "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Core/Infrastructure/MessageBus/AutofacMessageBus.cs"
    click Settings "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Core/Domain/Settings/JsonSettingStore.cs"
    click RulesDomain "https://github.com/changemakerstudios/papercut-smtp/tree/develop/src/Papercut.Rules/Domain"
    click RulesRunner "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Rules/App/RulesRunner.cs"
    click RuleModule "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Rules/PapercutRuleModule.cs"
    click MessageRepo "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Message/MessageRepository.cs"
    click SmtpStore "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Infrastructure.Smtp/SmtpMessageStore.cs"
    click ApiHost "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Service/PapercutServiceStartup.cs"
    click ApiHost "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Service/Program.cs"
    click Controllers "https://github.com/changemakerstudios/papercut-smtp/tree/develop/src/Papercut.Service/Application/Controllers"
    click SignalR "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Service/Web/Notification/NewMessagesHub.cs"
    click StaticAssets "https://github.com/changemakerstudios/papercut-smtp/tree/develop/src/Papercut.Service/Web/Assets"
    click InProcHost "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Service/Web/Hosting/InProcess/HttpServer.cs"
    click Electron "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Service/ElectronService.cs"
    click IPCommProto "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.Infrastructure.IPComm"
    click WPF "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.UI/App.xaml.cs"
    click UIModule "https://github.com/changemakerstudios/papercut-smtp/blob/develop/src/Papercut.UI/PapercutUIModule.cs"
```
