Sovite Structure

Every part of the codebase can be used as a library for other projects. The codebase is structured in a way that allows for modularity and reusability. Each module or component can be imported and utilized independently, making it easy to integrate into different applications or systems.

1. Layout

lib/
  sovite.ex          # Base application: starts the full MTA
  core/              # Sovite-only parts (the MTA itself)
  <component>/       # Reusable components, one folder each

2. Reusable Components

Each folder maps to one namespace: lib/<component>/ → Sovite.<Component>. Everything lives under Sovite.* to avoid module name clashes in projects that depend on Sovite.

Layer 0: Primitives (pure, no processes, no I/O)

Layer 1: Formats & Infrastructure

Layer 2: Protocols & Mail Authentication

Layer 3: Sovite Only

New components are added as new folders, placed in the lowest layer their dependencies allow.

Inside core/

lib/core/
  repo.ex            # Sovite.Core.Repo: picks the adapter, migrates at startup
  repo/
    migrations/      # one migration module per table (Sovite.Core.Repo.Migrations.*)
    schemas/         # one typed Ecto schema per table (Sovite.Core.Repo.Schemas.*)
    tables/          # one module per table that reads and writes it (Sovite.Core.Repo.Tables.*)
    data.ex          # helpers shared by the table modules
  config/            # config schema and cross-key checks
  cli/               # sovitectl commands
  delivery.ex        # Sovite.Core.Delivery: runs one job, SMTP here
  delivery/          # LMTP, local (Maildir and pipe), TLS policies, and the shared transaction/result code
  mail_auth.ex       # Sovite.Core.MailAuth: SPF/DKIM/ARC/DMARC checks, signing, sealing
  dmarc_reports.ex   # Sovite.Core.DMARCReports: aggregate report sender
  mta_sts.ex         # Sovite.Core.MTASTS: MTA-STS policies of recipient domains, cached
  tls_reports.ex     # Sovite.Core.TLSReports: TLS-RPT report sender
  screen.ex          # Sovite.Core.Screen: anti-abuse checks of SMTP clients
  greylist.ex        # Sovite.Core.Greylist: greylisting, stored in the database
  outbound.ex        # Sovite.Core.Outbound: suspends users whose mail fails too often
  milters.ex         # Sovite.Core.Milters: the milters of an SMTP session
  policy_service.ex  # Sovite.Core.PolicyService: check_policy_service in the restriction chains
  sendmail.ex        # Sovite.Core.Sendmail: sendmail(1), mailq(1), newaliases(1)
  control.ex         # Sovite.Core.Control: config reload, graceful drain, systemd notifications, status
  web.ex             # Sovite.Core.Web: the web server (Plug and Cowboy): UI, admin API, protections
  web/               # its router, API, pages, and security plugs
  cluster.ex         # Sovite.Core.Cluster: runs as a cluster node; the shared configuration
  cluster/           # sharing anti-abuse state, queue copies and takeover, which node delivers what
  tenants.ex         # Sovite.Core.Tenants: tenants, their limits and keys
  ip_pools.ex        # Sovite.Core.IPPools: outbound IP pools and warm-up schedules
  metrics.ex         # Sovite.Core.Metrics: the Prometheus metrics
  tracing.ex         # Sovite.Core.Tracing: the OpenTelemetry spans
  queue_info.ex      # Sovite.Core.QueueInfo: reading the queue for sovitectl and the API
  route_info.ex      # Sovite.Core.RouteInfo: how an address is routed, for sovitectl route
  log_reader.ex      # Sovite.Core.LogReader: reading Sovite's logs back, for trace.ex and log_report.ex
  postfix/           # reading Postfix's main.cf, master.cf, and tables, for sovitectl migrate postfix
  ...                # routing, rewriting, restrictions, queue manager

Every database table has its own migration, schema, and table module. Code outside core/repo/, including sovitectl, reaches the database only through the table modules (see AGENTS.md).

3. Dependency Rules

1. Dependencies only point downward. A component may depend on components in the same or lower layers, never higher.
2. Reusable components never depend on core/ or sovite.ex. If a reusable component needs something from core/, that something is either moved into a reusable component or injected via a behaviour/option.
3. No dependency cycles between components, even within the same layer.
4. Enforced in CI with mix xref graph --format cycles and a check that no reusable folder references Sovite.Core. The boundary library can make these compile-time errors.

4. Rules for Reusable Components

These rules are what make a component usable by other projects.

Configuration

• No Application.get_env/2 inside reusable components. All configuration is passed explicitly as function arguments or start_link options.
• Options are validated and documented (NimbleOptions-style schemas).

Processes

• Reusable components never start processes on their own. Stateful components expose a child_spec/1 so the caller places them in their own supervision tree.
• Every process accepts a :name option. No hard-coded global names, so several instances can run in the same VM (multiple servers, tests running concurrently, multi-tenant setups).
• Prefer pure functions; keep processes at the edges. Example: the SMTP session is a pure state machine (command + state → replies + new state + actions); the socket process around it is a thin shell.

Extension Points

• Anything environment-specific is a behaviour with a default implementation:
  • DNS resolver
  • Queue storage
  • Lookup table backend
  • SASL credential backend
  • SMTP server handler (callbacks for connect, HELO, MAIL, RCPT, DATA). This lets an app embed an SMTP receiver without the Sovite queue.
  • Delivery transport
• Tests use the same behaviours (fakes via Mox).

Observability

• Reusable components emit :telemetry events ([:sovite, <component>, ...]) instead of writing logs. The host application decides what to log.
• Pure layers (0 and most of 1) don't log at all.

API Style

• Return {:ok, value} / {:error, reason}, with ! variants where useful. Error reasons are documented structs or atoms, never raw strings.
• Message bodies are handled as streams / iodata, never required to be fully in memory.
• Never create atoms from untrusted input.
• Public modules have @moduledoc and @doc; internal modules are marked @moduledoc false and are not covered by semver.

Dependencies

• Keep required dependencies minimal.
• Heavy or backend-specific dependencies (PostgreSQL, MySQL, etc.) are declared optional: true; the modules that need them are only compiled when the dependency is present.

5. Base Application (lib/sovite.ex)

• lib/sovite.ex is the application entry point and starts the MTA tree from core/.
• When Sovite is used as a library dependency, the full MTA must not start automatically. The MTA only starts when explicitly enabled (for example by the release's runtime config); otherwise the application starts nothing and the reusable components are used directly.
• The MTA can also be embedded: the core/ supervisor exposes a child_spec/1 so another application can run Sovite inside its own supervision tree.

6. Tests

Tests mirror the source layout:

test/
  core/
  <component>/
  support/          # fake DNS, fake remote MTA, SMTP test client

• Each reusable component is tested in isolation, with no dependency on core/.
• core/ tests cover wiring and end-to-end mail flow.

7. Packaging

• Published as a single Hex package: sovite.
• Each component folder is kept self-contained so it could later be extracted into its own package (e.g. sovite_dkim) without breaking its public API.
• Docs (ExDoc) group modules by component, using groups_for_modules that match the folder layout.