# martinstromberg/gabriel architecture

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

- Interactive diagram: https://gitdiagram.com/martinstromberg/gabriel
- Repository: https://github.com/martinstromberg/gabriel

## Overview

##### Project type and purpose
- Gabriel is a standalone email server implemented in Go. Its primary functions are to accept incoming SMTP connections (receiving email) and to relay or send outgoing email to remote SMTP servers.
- This is a backend/network service, not a full-stack web application or GUI tool.

##### File structure
- cmd/gabrield.go: the main entry point that initializes and runs the server.
- internal/network: low-level TCP client and listener abstractions.
- internal/server: server configuration and the SMTP protocol handler.
- internal/submission: the SMTP “submission” functionality (SMTP verbs like HELO, AUTH, MAIL FROM, RCPT TO, DATA, STARTTLS, etc.), organized by concern (authentication, commands, data handling, recipient/sender logic).
- No frontend; no database subfolder—state is likely held in memory.

##### README
- Confirms that Gabriel’s goal is bidirectional email handling (send & receive).
- Mentions support for LOGIN and PLAIN authentication, potential future GSSAPI.

##### Main components
a. TCP Listener
- Accepts inbound connections on port 25 (or 587).
- Provided by internal/network/tcp_listener.go.
b. SMTP Protocol Handler
- Parses SMTP commands, manages session state.
- Located in internal/server/smtp.go, internal/server/config.go.
c. Submission Modules
- Authentication (LOGIN, PLAIN) – internal/submission/authentication.go
- Command handlers (HELO/EHLO, MAIL, RCPT, DATA) – internal/submission/*.go
- STARTTLS negotiation – internal/submission/start_tls.go
- Data and envelope processing – internal/submission/data.go, recipient.go, sender.go.
d. Network Client
- For outbound email delivery (acts as SMTP client) – internal/network/tcp_client.go.
e. Configuration
- Server options (ports, timeouts) – internal/server/config.go.
f. External Dependencies
- DNS for MX lookup (implicit or via Go stdlib).
- TLS libraries (Go crypto/tls).

##### Interactions and data flow
1. Client (external SMTP client or another mail server) → TCP Listener
2. TCP Listener → SMTP Protocol Handler
3. SMTP Handler → Submission Modules
- AUTH module verifies credentials
- MAIL/RCPT track envelope
- DATA module buffers message
- STARTTLS triggers TLS handshake
4. On successful DATA completion:
- Submission Module invokes Network Client
- Network Client resolves MX via DNS
- Network Client makes outbound TCP → remote SMTP server
5. Server responds back to original client with success/failure codes.

##### Architectural patterns and design principles
- Layered architecture:
- Network layer (listeners/clients)
- Transport layer (TCP/TLS handshake)
- Protocol layer (SMTP command parser)
- Application logic layer (submission, auth, data)
- Separation of concerns: each SMTP verb/feature lives in its own file.
- Dependency inversion: submission modules depend on abstracted network interfaces.

##### Detail
- SMTP verb/feature as its own sub-component.
- Call out configuration injection into both listener and handler.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Client["External SMTP Client"]:::external
    DNS["DNS (MX Lookup)"]:::cloud
    RemoteSMTP["Remote SMTP Server"]:::cloud

    %% Network Layer
    subgraph "Network Layer"
        direction TB
        TL["TCP Listener (Port 25/587)"]:::network
        NC["Network Client (Outbound SMTP)"]:::network
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        CL["Configuration Loader"]:::server
        SH["SMTP Protocol Handler"]:::server
    end

    %% Submission Layer
    subgraph "Submission Layer"
        direction TB
        CD["Generic Command Dispatcher"]:::submission
        HELLO["HELO/EHLO Handler"]:::submission
        AUTH["Authentication Module"]:::submission
        SENDER["MAIL FROM Processor"]:::submission
        RECIP["RCPT TO Processor"]:::submission
        DATA["DATA Module"]:::submission
        STARTTLS["STARTTLS Module"]:::submission
        RESET["Session Reset Handler"]:::submission
    end

    %% Flows
    Client -->|"TCP Connect"| TL
    TL -->|"Init Session"| SH
    CL -->|"Inject Config"| TL
    CL -->|"Inject Config"| SH
    SH -->|"Parse Commands"| CD
    CD -->|"HELO/EHLO"| HELLO
    CD -->|"AUTH"| AUTH
    CD -->|"MAIL FROM"| SENDER
    CD -->|"RCPT TO"| RECIP
    CD -->|"DATA"| DATA
    CD -->|"STARTTLS"| STARTTLS
    CD -->|"RSET"| RESET
    DATA -->|"On DATA Complete"| NC
    NC -->|"MX Lookup"| DNS
    DNS -->|"Return MX Record"| NC
    NC -->|"SMTP Session"| RemoteSMTP
    RemoteSMTP -->|"Response"| NC
    NC -->|"Relay Response"| SH
    SH -->|"Reply Codes"| TL
    TL -->|"SMTP Responses"| Client

    %% Click Events
    click TL "https://github.com/martinstromberg/gabriel/blob/main/internal/network/tcp_listener.go"
    click NC "https://github.com/martinstromberg/gabriel/blob/main/internal/network/tcp_client.go"
    click SH "https://github.com/martinstromberg/gabriel/blob/main/internal/server/smtp.go"
    click CL "https://github.com/martinstromberg/gabriel/blob/main/internal/server/config.go"
    click AUTH "https://github.com/martinstromberg/gabriel/blob/main/internal/submission/authentication.go"
    click HELLO "https://github.com/martinstromberg/gabriel/blob/main/internal/submission/hello.go"
    click CD "https://github.com/martinstromberg/gabriel/blob/main/internal/submission/command.go"
    click SENDER "https://github.com/martinstromberg/gabriel/blob/main/internal/submission/sender.go"
    click RECIP "https://github.com/martinstromberg/gabriel/blob/main/internal/submission/recipient.go"
    click DATA "https://github.com/martinstromberg/gabriel/blob/main/internal/submission/data.go"
    click STARTTLS "https://github.com/martinstromberg/gabriel/blob/main/internal/submission/start_tls.go"
    click RESET "https://github.com/martinstromberg/gabriel/blob/main/internal/submission/reset.go"

    %% Styles
    classDef network fill:#ccffcc,stroke:#006600,stroke-width:1px;
    classDef server fill:#cce5ff,stroke:#004080,stroke-width:1px;
    classDef submission fill:#ffe5cc,stroke:#cc6600,stroke-width:1px;
    classDef external fill:#f0f0f0,stroke:#666666,stroke-width:1px,stroke-dasharray: 2 2;
    classDef cloud fill:#eeeeee,stroke:#888888,stroke-width:1px,stroke-dasharray: 2 2;
```
