# aapanel/billionmail architecture

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

- Interactive diagram: https://gitdiagram.com/aapanel/billionmail
- Repository: https://github.com/aapanel/billionmail

## Overview

##### Project type and purpose
- BillionMail is a full-stack, self-hosted email server and email-marketing platform.
- It provides:
- A Vue.js SPA frontend for management and campaign building
- A Go-based REST API backend for business logic (contact management, campaigns, SMTP relays, analytics)
- Traditional mailserver components (Postfix, Dovecot, Rspamd) running in containers
- Data storage (SQL database), caching/queuing (Redis), and auxiliary services (ACME for SSL, fail2ban, supervisord)

##### File structure
- Top-level “Dockerfiles/” holds container definitions for core app and mailserver components.
- “core/” directory contains the Go monolith:
- cmd & main.go – entry point
- api/v1 controllers – HTTP handlers
- internal/service, logic, dao, model – layered business logic
- “core/frontend/” is a Vue 3 + TypeScript SPA, built and served as static assets.
- “manifest/” holds kustomize/Kubernetes and Docker Compose deployment manifests.
- “conf/” holds runtime configs for Postfix, Dovecot, Rspamd, PHP-FPM (RoundCube), fail2ban.
- “env_init” / “.env” is for Docker Compose environment variables.

##### Key insights from README
- It’s intended to deploy via Docker Compose or k8s.
- Core services include RESTful API, ACME integration, database initialization, scheduled tasks (timers).
- Frontend SPA communicates over Axios with core API.
- RoundCube WebMail is integrated behind `/roundcube/` via PHP-FPM container.

##### Relationships and data flow
1. User opens browser → loads Vue SPA → issues API calls
2. Vue → HTTP → Go API
3. Go API
– reads/writes to SQL DB
– interacts with Redis for caching, job control (e.g., batch mailing, warm-up)
– controls Docker API for dynamic container management (via `core/api/dockerapi`)
– invokes ACME service for SSL on user domains
– triggers mail tasks: enqueues send jobs
4. Mail tasks → Go service → hands off to Postfix via SMTP or direct send
5. Outbound mail passes through Rspamd (milter) → Postfix → recipient MTA
6. Inbound mail (for WebMail) → Dovecot → delivered to mailbox → accessible via RoundCube
7. fail2ban monitors logs and updates iptables to block suspicious traffic

##### Architectural patterns & principles
- Layered monolith (controller-service-dao-model) in Go
- Containerized micro-services for mailserver components
- Event/task queue using Redis for asynchronous batch mail, warm-up, analytics
- Plugin-style Sieve filters and periodic / timer jobs
- Configuration-as-code: Dockerfiles + supervisord + k8s manifests

##### Essential details to capture
- Docker Compose / k8s as the orchestration boundary.
- Supervisord controlling each container’s processes.
- ACME self-signed vs. production SSL path.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Agents
    subgraph "User Agents"
        User((User)):::user
        Browser["Browser"]:::user
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        Vue["Vue.js SPA Frontend"]:::frontend
        Static["Built Frontend Static Assets"]:::static
    end

    %% API Layer
    subgraph "API Layer"
        GoApp["Go REST API Backend"]:::backend
        Controllers["API Controllers (HTTP Handlers)"]:::backend
        ServiceLayer["Service Layer (Business Logic)"]:::backend
        DAO["Data Access Objects"]:::backend
        Model["Data Models"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["SQL Database (MySQL/MariaDB)"]:::db
        Redis["Redis (Cache, Queue)"]:::db
    end

    %% Mailserver Layer
    subgraph "Mailserver Layer"
        Postfix["Postfix SMTP MTA"]:::mail
        Rspamd["Rspamd Spam Filter"]:::mail
        Dovecot["Dovecot IMAP/POP3 & Sieve"]:::mail
        RoundCube["RoundCube WebMail (PHP-FPM)"]:::webmail
        Fail2ban["fail2ban Protection"]:::security
    end

    %% External Integrations
    subgraph "External Services"
        ACME["ACME Service (Let's Encrypt)"]:::external
        DockerAPI["Docker Engine API"]:::external
    end

    %% Orchestration & Management
    subgraph "Orchestration"
        Supervisord["Supervisord"]:::management
        Orchestrator["Docker Compose / Kubernetes"]:::management
        CLI["bm.sh / install.sh / update.sh"]:::management
    end

    %% Connections
    User -->|loads SPA| Vue
    Browser -->|HTTP GET| Static
    Vue -->|HTTP API calls| Controllers
    Controllers -->|calls| ServiceLayer
    ServiceLayer -->|CRUD| DAO
    DAO -->|maps| Model
    ServiceLayer -->|SQL queries| DB
    ServiceLayer -->|cache / queue| Redis
    ServiceLayer -->|invoke| DockerAPI
    ServiceLayer -->|request SSL| ACME
    ServiceLayer -->|enqueue mail jobs| Redis
    ServiceLayer -->|init DB| DB
    Redis -->|async jobs| ServiceLayer
    ServiceLayer -->|SMTP handoff| Postfix
    Postfix -->|milter| Rspamd
    Postfix -->|outbound SMTP| Internet
    Internet -->|inbound SMTP| Postfix
    Postfix -->|deliver| Dovecot
    Dovecot -->|mailbox| RoundCube
    RoundCube -->|IMAP/POP3| Dovecot
    User -->|WebMail access| RoundCube
    Fail2ban -->|monitor logs| Postfix
    Fail2ban -->|monitor logs| Dovecot
    Orchestrator --> Supervisord
    Supervisord --> Postfix
    Supervisord --> Rspamd
    Supervisord --> Dovecot
    Supervisord --> GoApp
    Supervisord --> RoundCube
    CLI --> Orchestrator

    %% Click Events
    click Vue "https://github.com/aapanel/billionmail/tree/dev/core/frontend"
    click Static "https://github.com/aapanel/billionmail/tree/dev/core/public/dist"
    click GoApp "https://github.com/aapanel/billionmail/blob/dev/core/main.go"
    click Controllers "https://github.com/aapanel/billionmail/tree/dev/core/api/v1"
    click ServiceLayer "https://github.com/aapanel/billionmail/tree/dev/core/internal/service"
    click DAO "https://github.com/aapanel/billionmail/tree/dev/core/internal/dao"
    click Model "https://github.com/aapanel/billionmail/tree/dev/core/internal/model"
    click ACME "https://github.com/aapanel/billionmail/tree/dev/core/internal/service/acme"
    click ACME "https://github.com/aapanel/billionmail/tree/dev/core/cmd/acme"
    click DockerAPI "https://github.com/aapanel/billionmail/tree/dev/core/api/dockerapi"
    click DockerAPI "https://github.com/aapanel/billionmail/tree/dev/core/internal/service/dockerapi"
    click DB "https://github.com/aapanel/billionmail/blob/dev/init.sql"
    click ServiceLayer "https://github.com/aapanel/billionmail/tree/dev/core/internal/service/database_initialization"
    click Redis "https://github.com/aapanel/billionmail/tree/dev/core/internal/service/redis_initialization"
    click Redis "https://github.com/aapanel/billionmail/tree/dev/conf/redis"
    click Postfix "https://github.com/aapanel/billionmail/tree/dev/Dockerfiles/postfix"
    click Postfix "https://github.com/aapanel/billionmail/tree/dev/conf/postfix"
    click Rspamd "https://github.com/aapanel/billionmail/tree/dev/Dockerfiles/rspamd"
    click Rspamd "https://github.com/aapanel/billionmail/tree/dev/conf/rspamd"
    click Dovecot "https://github.com/aapanel/billionmail/tree/dev/Dockerfiles/dovecot"
    click Dovecot "https://github.com/aapanel/billionmail/tree/dev/conf/dovecot"
    click RoundCube "https://github.com/aapanel/billionmail/tree/dev/conf/php"
    click RoundCube "https://github.com/aapanel/billionmail/tree/dev/conf/webmail"
    click Fail2ban "https://github.com/aapanel/billionmail/blob/dev/Dockerfiles/core/fail2ban.conf"
    click Fail2ban "https://github.com/aapanel/billionmail/blob/dev/Dockerfiles/core/restart_fail2ban.sh"
    click Fail2ban "https://github.com/aapanel/billionmail/tree/dev/conf/core/fail2ban_init"
    click Supervisord "https://github.com/aapanel/billionmail/blob/dev/Dockerfiles/core/supervisord.conf"
    click Supervisord "https://github.com/aapanel/billionmail/blob/dev/Dockerfiles/postfix/supervisord.conf"
    click Supervisord "https://github.com/aapanel/billionmail/blob/dev/Dockerfiles/dovecot/supervisord.conf"
    click Supervisord "https://github.com/aapanel/billionmail/blob/dev/Dockerfiles/rspamd/supervisord.conf"
    click Orchestrator "https://github.com/aapanel/billionmail/tree/dev/core/manifest/deploy/kustomize"
    click Orchestrator "https://github.com/aapanel/billionmail/tree/dev/core/manifest/docker"
    click Orchestrator "https://github.com/aapanel/billionmail/blob/dev/docker-compose.yml"
    click CLI "https://github.com/aapanel/billionmail/blob/dev/bm.sh"
    click CLI "https://github.com/aapanel/billionmail/blob/dev/install.sh"
    click CLI "https://github.com/aapanel/billionmail/blob/dev/update.sh"

    %% Styles
    classDef user fill:#D0E6A5,stroke:#598527,color:#000
    classDef frontend fill:#A0D8F1,stroke:#017BFF,color:#000
    classDef static fill:#E1F5A9,stroke:#7AAC0A,color:#000
    classDef backend fill:#F9E79F,stroke:#B7950B,color:#000
    classDef db fill:#ABEBC6,stroke:#229954,color:#000
    classDef mail fill:#F5B7B1,stroke:#C0392B,color:#000
    classDef webmail fill:#D2B4DE,stroke:#6C3483,color:#000
    classDef security fill:#FADBD8,stroke:#922B21,color:#000
    classDef external fill:#D6EAF8,stroke:#1F618D,color:#000
    classDef management fill:#FDEBD0,stroke:#B9770E,color:#000
```
