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