bongo/docs/architecture.md

Architecture

Bongo is an integrated but modular mail, calendar, and contact server. A small manager supervises specialised agents which share the Bongo Store and Queue instead of combining every protocol in one process.

Message flow

A typical Internet message follows this path:

1. bongosmtp accepts SMTP and applies listener, relay, TLS, authentication, and message-size policy.
2. bongoqueue records and routes the message through enabled filtering agents.
3. SPF, DKIM, DMARC, SRS, SpamAssassin, ClamAV, and Sieve processing run where configured.
4. Local delivery commits the message through bongostore; remote delivery is performed by bongosmtpc or a configured LMTP/SMTP transport.
5. Users read the same stored data through IMAP, POP3, or the Web interface.

External account collection enters the same delivery path: bongocollector fetches a user's remote POP3 or IMAP account and submits the message to the mailbox selected by that user. Sending with a matching external identity is handled by the authenticated outbound SMTP path.

Components

Component	Responsibility
bongo-manager	Starts the Store first, then enabled agents in priority order.
bongostore	Owns per-user mail, calendar, contact, and metadata storage.
bongoqueue	Spools, filters, and routes messages.
bongosmtp	Receives SMTP, submission, and trusted-device relay traffic.
bongosmtpc	Sends SMTP and LMTP deliveries.
bongoimap	Provides IMAP4rev2, IMAP4rev1, and legacy IMAP4 access.
bongopop3	Provides POP3 and POP3S access.
bongosieve	Provides the ManageSieve protocol.
bongorules	Executes Sieve filtering and vacation actions.
bongocollector	Fetches user-configured external accounts.
bongoantispam	Connects to SpamAssassin when enabled.
bongoavirus	Connects to ClamAV when enabled.
Bongo Web	Python 3 Webmail, account settings, CalDAV, and CardDAV.
bongo-setup / bongo-admin	Guided initial setup and validated administration.

Agents use common C libraries for configuration, logging, authentication, TLS, protocol I/O, Store access, and Queue access. GNU GSASL is shared by the mail protocols; its direct Bongo verification callback does not create or consult a second user database.

Internal interfaces

The Store protocol on TCP 689 and Queue protocol on TCP 8670 are private service interfaces. They are not substitutes for IMAP, SMTP, or a public API and must not be exposed to untrusted networks. The manager and local tools use them to coordinate the agents.

The Web process talks to the maintained Python 3 bindings and Store services. Its HTTP listener defaults to loopback because TLS is normally terminated by Apache, nginx, or another trusted reverse proxy. This does not hard-code an external http:// URL: public_base_url, forwarded-address trust, and HTTPS status are explicit deployment settings.

Direct HTTPS is also supported. The Web agent binds port 443, loads the configured certificate and private key, binds port 80 for an HTTPS-only redirect, and then permanently changes its real and effective UID/GID to the configured bongo service account before accepting either HTTP listener.

Configuration model

Agent settings are operative suffixless JSON Store documents such as smtp, imap, queue, web, authentication, and manager. Their declarative counterparts live below /etc/bongo/config.d; alias fragments live below /etc/bongo/aliases.d. The manager validates and imports the files only after the Store starts, so agents always consume one coherent Store-facing model and never fall back to a second runtime configuration source.

bongo-admin config reads the Store and writes Store plus files as one rollback-capable operation. Use bongo-admin config check for a read-only file validation and bongo-admin config sync after direct or automated file changes. Pre-0.7 layouts require the explicit one-time migration command.

Design direction

The original Dragonfly artwork and layout remain the visual basis for the 0.7 Web interface. The implementation is maintained Python 3 and JavaScript; no Ruby runtime or Ruby rewrite is planned. A later responsive redesign should preserve the simple integrated product rather than introduce a second server stack.