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. |

Protocol and component details are maintained in [smtp.md](smtp.md),
[imap.md](imap.md), [pop3.md](pop3.md), [sieve.md](sieve.md),
[queue.md](queue.md), [web.md](web.md), and [dav.md](dav.md).

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.

Agents which bind a privileged listener start with the manager's restricted
credentials, bind, and permanently change their real/effective/saved UID and
GID to `bongo` before accepting clients. Non-listener agents do the permanent
drop immediately. The manager itself normally has effective UID `bongo` but
retains a bounded supervisor identity so a crashed listener can be replaced.
`bongoworker` has the same inactive exception solely for the short atomic ACME
certificate deployment step. systemd restricts both to `CHOWN`,
`DAC_OVERRIDE`, `FOWNER`, `SETGID`, `SETUID`, and `NET_BIND_SERVICE`; active
and ambient capabilities are empty while idle. Moving ACME deployment into a
smaller dedicated privileged helper remains a future hardening improvement.

The systemd service additionally uses a strict read-only filesystem view with
explicit write access only to Bongo state, runtime PID files, synchronized
configuration, and TLS deployment paths. Kernel, control-group, device,
hostname, realtime, SUID/SGID-creation, and non-Internet/non-Unix address
families are isolated. Required state and configuration mounts and
systemd-tmpfiles setup are ordered before the manager starts.

## 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.

For 0.9, JMAP becomes the canonical public object and synchronisation model,
while `bongostore` remains the only durable data owner. IMAP, POP3,
ManageSieve, CalDAV, CardDAV, SMTP/LMTP delivery, and the Web interface map to
the same internal objects and compatibility metadata; they do not maintain
parallel databases. See [JMAP and the Bongo Store](jmap.md).