# spartasystems/holdmail architecture

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

- Interactive diagram: https://gitdiagram.com/spartasystems/holdmail
- Repository: https://github.com/spartasystems/holdmail

## Overview

##### Project Type & Purpose
- It is a full-stack application with clearly separated backend and frontend components.
- The backend is built with Java 8+ using Spring Boot. It acts as both an SMTP server (to accept, store, and forward emails) and a REST service exposing endpoints to list, view, and forward messages.
- The frontend, built using Vue.js, provides a user interface to search and inspect received emails.
- Additional components (database, Docker, scripts) support deployment and configuration.

##### Key Architectural Components
a. Frontend (Client):
– Located in the “client” directory.
– Built with Vue.js, utilizing webpack (with production and development configuration files) and Babel.
– Communicates with the backend REST endpoints to fetch mail data.

b. Backend (Server):
– Core Spring Boot application found under “src/main/java/com/spartasystems/holdmail”.
– Contains subcomponents organized into domains (domain models representing emails and attachments), REST controllers for API endpoints, service logic for managing emails, and SMTP server components (HoldMailSMTPServer, SMTPHandler, etc.) which simulate email relay.
– Uses Spring Data (repository classes) and JPA entities (e.g., MessageEntity, MessageHeaderEntity) for persistence.

c. Database:
– By default, an embedded H2 database is used (configured via application.properties), with migration scripts provided under “src/main/resources/db/migration”.
– Option to swap to an external database like MySQL by overriding Spring Boot datasource settings.

d. REST API:
– Exposed endpoints for listing messages, fetching raw and parsed content (text, HTML), retrieving attachments, and forwarding emails.
– Utilizes standard HTTP methods (GET for fetching data, POST for forwarding messages) and clearly defined URI paths (/rest/messages, etc.).

e. SMTP Server:
– A “fake” SMTP relay running on a designated port (default 25000) for capturing and storing emails.
– Contains components for handling SMTP sessions, processing MIME types, and integrating with the service layer.

f. Deployment & Build Infrastructure:
– Gradle build scripts (build.gradle, settings.gradle) compile both backend and frontend.
– Docker configuration (Dockerfile, docker-compose.yml) and RPM packaging scripts support containerization and system deployments.
– Travis CI and other configuration files (in .github, .travis.yml) ensure continuous integration.

##### Interactions & Data Flow
– Show REST API endpoints providing access to mail data and how the Vue.js client communicates with these endpoints.
– Indicate that email forwarding, once triggered by the client or other application, routes messages to an external SMTP relay.
– Represent external configuration sources such as property files (/etc/holdmail.properties) and environment settings.

##### Architectural Patterns & Design Principles
– MVC: The separation between the frontend (view layer, handled by Vue.js) and backend (controller, service, and model layers in Spring Boot) is evident.
– Microcomponent / Layered Pattern: Split the backend into presentation (REST controllers), business logic (services), and data access layers (repository/persistence).
– Containerization: Docker and Gradle support are present for build automation and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Vue.js Client"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        REST["Spring Boot REST API"]:::backend
        SMTP["Fake SMTP Server"]:::backend
        DOMAIN["Domain & Persistence"]:::backend
        SMTPComp["SMTP Components"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["Database (H2/MySQL)"]:::database
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        DOCKER["Docker Configuration"]:::deployment
        BUILD["Build Scripts"]:::deployment
        CI["CI/CD Pipeline"]:::deployment
    end

    %% External Entities
    External["External Email"]:::external
    SMTPRelay["External SMTP Relay"]:::external

    %% Data Flow & Interactions
    External -->|"SMTPsession"| SMTP
    SMTP -->|"StoresEmail"| DOMAIN
    DOMAIN -->|"PersistsIn"| DB
    FE -->|"APICalls"| REST
    REST -->|"QueriesEmails"| DOMAIN
    REST -->|"ForwardsMail"| SMTPRelay
    SMTP -->|"Uses"| SMTPComp

    %% Deployment Flow
    BUILD -->|"Builds"| FE
    BUILD -->|"Builds"| REST
    DOCKER -->|"Containers"| FE
    DOCKER -->|"Containers"| REST
    CI -->|"IntegratesWith"| BUILD

    %% Click Events
    click FE "https://github.com/spartasystems/holdmail/blob/master/client/src/main.js"
    click REST "https://github.com/spartasystems/holdmail/tree/master/src/main/java/com/spartasystems/holdmail/rest"
    click DOMAIN "https://github.com/spartasystems/holdmail/tree/master/src/main/java/com/spartasystems/holdmail/domain"
    click SMTP "https://github.com/spartasystems/holdmail/tree/master/src/main/java/com/spartasystems/holdmail/smtp"
    click DB "https://github.com/spartasystems/holdmail/tree/master/src/main/resources"
    click BUILD "https://github.com/spartasystems/holdmail/blob/master/build.gradle"
    click DOCKER "https://github.com/spartasystems/holdmail/tree/master/Dockerfile"
    click CI "https://github.com/spartasystems/holdmail/blob/master/.travis.yml"

    %% Styles
    classDef frontend fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef backend fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef database fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef deployment fill:#ffe6c9,stroke:#d35400,stroke-width:2px;
    classDef external fill:#ffebcc,stroke:#f39c12,stroke-width:2px;
```
