Architecture Overview
This directory contains the codified architectural decisions for Substratum v1.0. These documents outline the core design philosophies, system boundaries, and implementation strategies that guide the development of the SaaS dashboard, the Identity-Gated Gateway, and the local Sidecar.
Core Design Principles
Substratum is designed for long-term sovereignty, testability, and eventual decomposition. We prioritize modularity over rapid MVP monolithic coupling.
Ubiquitous language: Canonical product and engineering terms are defined in the Glossary. ADRs and new docs should link there instead of redefining terms.
Architecture Decision Records (ADRs)
We track architectural decisions and proposals using ADRs. Please read the following documents in order to understand the system design:
| ADR | Title | Status | Description |
|---|---|---|---|
| 01 | The Modular Monolith | Accepted | Why we are building a single logical boundary partitioned into publishable modules. |
| 02 | Ports and Adapters | Accepted | How we isolate the core domain logic from the network, storage, and user interfaces. |
| 03 | Network Behavior | Accepted | Why we are not forking IPFS, and how we swap modules to create a private swarm. |
| 04 | Sidecar Design | Accepted | The architecture of the local agent, starting as a headless daemon. |
| 05 | Phase 1 Scope | Accepted | The minimal set of adapters and domain logic required for the initial implementation. |
| 06 | Documentation Hosting | Accepted | How we use Tangled's Spindle CI to build and deploy VitePress to a tngl.sh domain. |
| 07 | Core Language Selection | Proposed | Selecting the primary language for the core domain, Sidecar, and Gateway. |
| 08 | Hosting and Frontend Stack | Accepted | Defining the infrastructure (DigitalOcean) and UI framework (Mithril.js). |
| 09 | Database and ORM (SeaORM) | Accepted | Using DO Managed PostgreSQL and SeaORM (Rust) for Native RLS. |
| 10 | Repository Structure | Accepted | Polyglot Monorepo (Nx + Cargo) and the 4-pillar Gateway architecture. |
| 11 | Cross-Boundary Strategies | Accepted | WASM for client-side crypto, OpenAPI (utoipa), and the Actor Pattern. |
| 12 | AT Protocol Integration | Accepted | Leveraging the atproto-* workspace for identity, OAuth, and DPoP. |
| 13 | Twelve-Factor App | Accepted | Ensuring cloud-native scalability, config management, and disposability. |
| 14 | Frontend Internationalization | Accepted | Lingui, hand-maintained JSON catalogs, explicit IDs, and ui-kit boundaries for the Mithril dashboard. |
| 15 | Web File Explorer | Accepted | Miller columns, TanStack virtual-core windowing, selection and prefetch, Passport-driven affordances in apps/file-explorer. |
| 16 | Drive-Centric Domain Vocabulary | Accepted | Conway-aligned naming: Drive (not Vault) for the user-scoped root in APIs, ingress DTOs, and UI; folders and files under it. |
| 17 | Multi-Tenant PSK Injection | Accepted | Using Secure WebSockets (WSS) and HTTP Upgrades to dynamically inject user-specific PSKs into a single libp2p Swarm. |
| 18 | Gateway Connectivity Presence and Push Updates | Proposed | Define a hybrid browser connectivity model combining online/offline signals, adaptive health probing, and server push events for responsive gateway status UX. |
| 19 | Rust Build Optimization | Accepted | Strategies for fast Cargo compilation (lld, sccache) and manual Nx project.json graph integration. |
| 20 | File Explorer Service Layer | Accepted | Service interfaces, singleton composition, RxJS-backed state, resolver adapters, and OpenAPI-aligned API URLs in apps/file-explorer. |
| 21 | Passport Lexicons and Ref-Only AT Protocol Records | Superseded (in part) | cloud.substratum.* lexicons and ref-only records; detached provenanceSignature superseded by ADR 27. |
| 22 | Drive Lexicon and Persistence | Accepted | Canonical drive metadata schema, dual persistence in swarm and DB, and native RLS-backed listing. |
| 23 | Personal Unified Installer and Cross-Platform Kit | Accepted | Single onboarding story and config contract across macOS, Windows, Android, and iOS; Tauri orchestrator on desktop; storage policy from installer, enforcement in node runtime. |
| 24 | Installer post-MVP — mesh modes, explicit roles, and cloud relay | Proposed | Step 0 hosting topology (self-hosted vs cloud); cross-platform install_self_hosted; Postgres port 35432; mesh_mode / installer profile separate from triangle JSON; explicit device selection; discovery plug-ins. |
| 25 | Directory Lexicons and First-Class Passports | Proposed | Elevate directories to first-class cryptographic objects with their own AT Protocol lexicons and verifiable passport receipts, removing frontend shims. |
| 26 | TUS Resumable Drive Uploads | Proposed | tus.io transport via fileloft, drive-scoped routes, finalize into swarm/DB, batch SSE progress, file-explorer integration; deprecate multipart upload after rollout. |
| 27 | Zero Trust PDS-Based Provenance | Accepted | Enforcing Zero Trust by using the user's PDS to sign cloud.substratum.passport.receipt records via createRecord, replacing Gateway Attestation. |
| 28 | Receipt Sync Queue and Grantee Access Removal | Accepted | Transactional outbox to converge Postgres catalog ACL on owner-repo receipts; grantee accessRemovalRequest on grantee PDS; shared pipeline for gateway and home-base. |
| 29 | Private PDS Namespace and Local CAR Emergency Export | Proposed | Private cloud.substratum.* collections; local .car vault; break-glass mesh deferred. |
| 30 | Catalog–PDS Dual-Write | Proposed | Filesystem lexicons (filesystem.drive / driveEntry / directory) catalog↔PDS via CatalogSyncWorker; passport private namespace is a separate ADR 29 refactor on receipt sync. |
| 31 | Personal kit updates and in-app update checks | Proposed | Kit Release Manifest, Update Coordinator, built-in checks in installer/Substratum/explorer; phased path from installer-only refresh to signed remote apply. |
| 32 | Account entitlements and hosting policy | Proposed | Three policy layers (hosting, account plan, node disk); deployment_mode, UploadPolicy, GET /me/limits; SaaS-only ingress enforcement; /account UI. |
| 33 | Frontend modular monolith and package boundaries | Accepted | One web SPA and shared libraries—not runtime micro-frontends; in-process shell, feature folders, deployment-aware nav. |
| 34 | Idempotent Directory Creation and Concurrency | Accepted | Preventing duplicate entries and race conditions during high-concurrency nested folder uploads. | | 35 | Drive Node Delete (Four-Layer Removal) | Proposed | Four delete layers (catalog, PDS tombstones, quota/local GC, triangle unpin + DLQ) plus Account sync-failures dashboard (/account/sync-failures, GET /api/v1/me/sync-failures) for DELETE /api/v1/drives/{id}/nodes. | | 36 | Marketing Landing Page | Accepted | apps/landing on DO Droplet + Caddy; Spindle rsync deploy; build-time prerender per locale; families-first Midnight Gallery SPA; v1 Pricing section (Coming soon badges). | | 37 | PDS Entitlement Proxy and Payment-Provider-Agnostic Billing | Proposed | Entitlement service + PDS repo authz proxy for cloud.substratum.*; billing adapters (Stripe one of many); deleteRecord allowed on lapse for migration; gateway/home sync uses same capabilities. | | 38 | Support and Entitlement Admin Tooling | Proposed | v1 operator admin API + manual billing adapter + audit log; Discourse hooks; PDS company SSO + localized operator UI (apps/admin at admin.*); closes ADR 32 CC10. | | 39 | AT Protocol OIDC Bridge for Discourse Support SSO | Proposed | id.support.* OIDC provider → AT Proto OAuth on pds.*; entitlement-gated Discourse login at support.*; reuses crates/auth. | | 40 | Orval Fetch Mutators for Cross-App HTTP Clients | Accepted | createApiFetch() per OpenAPI surface; Orval override.mutator for cookie auth and global 401 handling; ops live, gateway migration planned. | | 41 | Operated PDS Hosting Topology and AT Protocol Plane Separation | Proposed | Garage v1 single Tranquil PDS; Postgres repo store + Spaces blobs; stateless droplet; gateway as product read plane (AppView analog); defer Entryway/sharding. | | 42 | Branded PDS Portal (apps/pds-portal) | Accepted | ui-kit SPA on pds.* for sign-in and OAuth consent; keep Tranquil upstream; signup stays gateway-mediated on app.*; phased account-security and Tranquil fallback. | | 43 | Centralized Log Observability | Proposed | Vector on edge droplets → Loki + Grafana on infra/observability; Phase 1 local disk; optional Phase 2 Spaces chunk storage. | | 44 | Explorer Workspace Decomposition | Proposed | Thin ExplorerWorkspace orchestrator; extend explorerTreeService.refreshPath; coordinator modules in lib/ / components/explorer-workspace/; URL stays source of truth for path and panels. |