# 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. Cyrus SASL is shared by
the mail protocols; it does not create 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.

## Configuration model

Most agent settings are JSON objects stored as suffixless Store documents,
for example `smtp`, `imap`, `queue`, and `manager`. The missing `.json` suffix
is intentional and is consistent in the source templates and installed
templates.

Settings required before the Store is available remain local:

- `/etc/bongo/bongo.conf` contains authentication and LDAP bootstrap policy.
- `/etc/bongo/bongo-web.json` contains the Web listener, session, proxy, and
  local Web database settings.

Use `bongo-admin config` or `bongo-admin config check` so related documents
are validated together. Avoid editing live Store documents independently.

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