ADR 01: The Modular Monolith

Status: Accepted Date: 2026-04-09

Substratum is built as a Modular Monolith. This means the entire system (SaaS, Gateway, Sidecar) is developed within a single logical repository and application boundary, but it is strictly partitioned into independent, publishable modules.

The Philosophy

Instead of starting with a complex microservices architecture (which introduces network overhead and deployment complexity) or a tangled "big ball of mud" monolith, we enforce strict internal boundaries.

Core Principles

1. Strict Boundaries: The domain logic (e.g., verifying AT Proto Auth, generating Swarm PSKs, checking Passport ACLs) lives in the center. It has no dependencies on the web framework, the database ORM, or the HTTP server.
2. Publishable Artifacts: Each module is designed to be compiled and published as an independent artifact (e.g., a Rust crate, a Go module, or an NPM package).
3. Zero-Rewrite Decomposition: When a specific component needs to scale independently—for example, when the Gateway needs to serve 10,000 video streams while the SaaS dashboard only handles 10 users clicking "Billing"—we can extract the gateway module and deploy it as a separate microservice. Because the boundaries are strict, this requires zero rewriting of the underlying domain logic.

Module Structure

While the exact directory structure depends on the chosen language stack, the logical separation is:

• Core Domain: Shared types, schemas (Passport Receipt), and AT Proto utilities.
• P2P Network: The modular libp2p implementation.
• Sidecar Application: The local desktop/CLI agent logic.
• Gateway Application: The high-speed proxy logic.
• SaaS Application: The web dashboard and billing logic.