Substratum Glossary (Ubiquitous Language)
Last Updated: 2026-06-12
This page is the canonical vocabulary for Substratum product, documentation, APIs, and UI copy. Use these terms consistently so families, operators, and engineers share one mental model.
Related: ADR 16: Drive-Centric Domain Vocabulary · ADR 24: Hosting topology and mesh modes · Technical specification
How to use this glossary
| Label | Meaning |
|---|---|
| Preferred | Use in user-facing copy, OpenAPI, and new docs. |
| Config | Exact string in JSON, env, or code (often snake_case). |
| Deprecated | Do not use in new public contracts; migrate readers to the preferred term. |
| Informal | Spoken shorthand only; define the preferred term in the same sentence when writing docs. |
When two axes are independent (for example who runs the API vs how nodes connect), never merge them into one word like “cloud” or “home.”
Product and deployment
| Term | Definition |
|---|---|
| Substratum | The private storage network and software kit: gateway, mesh nodes, file explorer, and personal installer. |
| SaaS (Substratum Cloud) | Preferred for Substratum-operated hosting: the gateway, catalog database, and web UI run on infrastructure Substratum runs (the Global Triangle and managed services). Users sign in with AT Protocol; account plan limits (upload size, quotas) apply here. |
| Self-hosted | Preferred when the family runs the full stack on their own hardware (home server). Config: hosting_topology: self_hosted in the installer profile. The operator controls disk on each mesh node; Substratum does not impose account byte caps on that gateway. |
| Cloud-connected | Preferred when mesh nodes stay on user hardware but the API and catalog live on Substratum Cloud. Config: hosting_topology: cloud_connected. Lower ops burden than self-hosted; distinct from “everything runs in the cloud.” |
| Homebase | Informal for Substratum-hosted API/catalog path (SaaS or cloud-connected API). In specs and config, prefer Substratum Cloud, SaaS, or cloud_connected so hosting vs mesh stay clear. |
| Hosting topology | Config axis: who runs the gateway API and Postgres catalog. Values: self_hosted, cloud_connected. Chosen in installer Step 0. See ADR 24. |
| Mesh mode | Config axis: how the three personal nodes reach each other. Values: private_hardware (no Substratum relay) or cloud_relay (optional Substratum-operated relay/bootstrap). Independent of hosting topology. |
| Deployment context | Umbrella for UI and policy: saas, self_hosted, or homebase (cloud-connected + relay). Gateway exposes deployment_mode (saas | self_hosted) for limits and copy—not guessed from the browser URL. See ADR 32. |
| Personal Device Triangle | Exactly three user-owned libp2p identities that form the personal mesh. Provisioned by the installer; materialized as per-device substratum-triangle.json files. |
| Family operator | The person who runs install, storage paths, and home server upkeep once; other members use folders and albums day to day. |
| Content-level sharing | Preferred. Sharing is expressed per file or folder (Passport access control), not “row-level” or “whole database” access. |
| CTA (call to action) | A button or link that prompts the next user step (for example upgrade plan, download installer, open self-host docs). In file-explorer, targets often come from API URL fields on GET /me/limits (upgrade_url, installer_download_url, docs_self_host_url) rather than hardcoded routes. See ADR 32. |
| Your existing login | Preferred customer copy. Sign in with Bluesky, Tangled, or another AT Protocol handle hosted elsewhere. No Substratum sign-in fee; upstream provider sets identity risk and repo policy. Config/engineering: BYO PDS. See Business model. |
| Substratum login and file metadata | Preferred customer copy. Paid Substratum-operated sign-in plus ownership records (Passport receipts) we anchor for you. Signup gated on subscription or lifetime license. Config/engineering: Substratum-hosted PDS. |
| Support | Substratum-operated sign-in continuity and export, plus self-hosted Discourse at support.* for paid Substratum login customers. Not bundled for your existing login only. See Business model. |
| Safety-net storage | Optional metered multi-region copies Substratum operates; home copies remain under customer control. Preferred public term—not “vault” or “cloud-only.” |
| Substratum Once | $99 one-time for the by-product only: managed Substratum login and file metadata and support. No included safety-net storage. See Business model. |
| Base membership | $5/month for managed login and metadata plus safety-net storage (25 GB included) and $0.12/GB/mo overage. Home-to-home sync is not part of this offering—it is built into the protocol/software. |
Identity and authentication
| Term | Definition |
|---|---|
| AT Protocol (ATProto) | Open protocol for identity, repos, and federation. Substratum uses it for AuthN/AuthZ only—no proprietary user database. |
| Decentralized Identifier (DID) | Preferred identifier for a user, typically did:plc:…. Config/field: did. Owner of drives and signer of provenance via their PDS. |
| Handle | Human-readable name (for example alice.bsky.social) resolved to a DID. |
| Personal Data Server (PDS) | The user’s AT Protocol repository host. OAuth and createRecord for Passport receipts go through the PDS. |
| OAuth (3-legged) | Sign-in flow: handle → DID → redirect to PDS → session JWT for the gateway. |
| Demonstration of Proof-of-Possession (DPoP) | Binding between OAuth tokens and the client; used when the gateway writes receipts on the user’s repo. |
Storage and catalog
| Term | Definition |
|---|---|
| Drive | Preferred user-scoped root of a private namespace: policy boundary, folder tree, and pinning scope. API: drive_id. Deprecated public term: Vault / vault_id. See ADR 16. |
| Folder | Directory inside a drive; may contain files and subfolders. |
| File | Blob inside a drive; content-addressed blocks on the mesh. |
| Passport receipt | Preferred metadata record (cloud.substratum.passport.receipt) anchoring ownership and access control in the owner’s PDS. See Passport receipt schema and ADR 27. |
| Access control | List of principals (DIDs, groups) allowed to view content; enforced with provenance on the mesh. User-facing copy: people, groups, share link—not “ACL” in the UI. |
| Content Identifier (CID) | IPFS-style hash of block content. Upload/fetch: use asset_cid for block reads; receipt_cid may change after PDS sync (ADR 28). |
| Catalog | Gateway Postgres metadata (drives, tree entries, ACL mirrors) aligned with PDS receipts. |
| Blockstore | Object storage for raw blocks (S3-compatible on cloud; local path on self-hosted). |
| Account plan | SaaS entitlement for a DID (upload limits, quotas). Does not apply to self-hosted gateways. See ADR 32. |
| Node storage policy | Per-device disk path and optional max_bytes / warn_bytes on a triangle node—operator choice in installer Step 3, not Substratum billing. |
| Swarm block cap | SWARM_MAX_BLOCK_BYTES (25 MiB): max payload per PutBlock on the private mesh. Smaller than the ingress upload ceiling; large files require upload ingest chunking (ADR 32). |
Network and mesh
| Term | Definition |
|---|---|
| Hybrid mesh | Global Triangle (cloud) plus local nodes (sidecar / home hardware) under per-user private swarms. |
| Global Triangle | Preferred name for the three Substratum-operated cloud libp2p nodes (multi-region). Static bootstrap; not public DHT. |
| Sidecar | Preferred local agent (daemon or container) on user hardware: joins the user’s private swarm, optional local gateway. |
| Gateway | Preferred HTTPS API front door (apps/gateway): OAuth, drive CRUD, upload, catalog. Implemented as a modular monolith (ingress + auth + resolution + retrieval). |
| Ingress | HTTP/OpenAPI layer inside the gateway (crates/ingress); DTOs and route handlers. |
| Private swarm | libp2p network isolated per user via a derived Pre-Shared Key (PSK). |
| Pre-Shared Key (PSK) | 256-bit swarm secret derived from master material and user DID; limits blast radius if one node is compromised. |
| Cloud relay | Config: mesh_mode: cloud_relay. Substratum-operated connectivity helpers; not a fourth triangle owner. |
| Private hardware | Config: mesh_mode: private_hardware. Nodes reach each other without Substratum relay (VPN, LAN, Tailscale, etc.). |
| Tailscale | Optional discovery overlay used by the installer; not required for all deployments. |
Applications and UI
| Term | Definition |
|---|---|
| File explorer | Preferred web app (apps/file-explorer) for browsing drives, upload, and sharing. |
| Application shell | Shared header, sidenav, locale, and session chrome inside the file-explorer SPA (not a micro-frontend host). Nav items may follow a manifest filtered by deployment context. See ADR 33. |
| Modular frontend monolith | Preferred web UI shape: one Vite build (apps/file-explorer), strict libs/ boundaries (ui-kit, api-client, optional platform/shell libs)—no runtime micro-frontends. |
| Feature package | Logical area (explorer, account, auth) as folders and services under the web app or a workspace library—not a separately deployed SPA. |
| Installer (GUI) | Desktop Tauri wizard (apps/installer-gui) for triangle setup, hosting choice, storage policy, and self-hosted install. |
| Substratum Explorer | Desktop Tauri shell (apps/substratum-explorer) that opens the self-hosted edge URL in a webview. |
| Express install | Installer Step 4: OS packages (if needed) + install_self_hosted + health check. |
| Edge | Reverse proxy (for example Caddy) serving the static UI and proxying /api to the internal gateway port. Self-hosted default public port: 35480. |
| Shared with me | Explorer view of content shared to the signed-in user via Passport access control. |
Artifacts and configuration
| Term | Definition |
|---|---|
substratum-triangle.json | Per-device cryptographic and peer-list contract for the three-node mesh. See triangle v1 reference. |
| Installer profile | substratum-installer-profile.json: hosting topology, mesh mode, ports, install paths—separate from triangle crypto. See installer profile v1. |
| Gateway application config | substratum-gateway.json (optional): operational settings merged with env. |
| Kit / personal kit | Cross-platform installer + explorer + staged bundles for home deployment (ADR 23, ADR 31). |
Architecture patterns
| Term | Definition |
|---|---|
| Modular monolith | Preferred backend shape: one deployable process, strict internal module boundaries (core, auth, ingress, retrieval)—not microservices for v1. See ADR 01. |
| Modular frontend monolith | Same idea on the web: one SPA deployable, separated libraries and feature folders—not micro-frontends. See ADR 33. |
| Ports and adapters | Hexagonal pattern: domain logic decoupled from HTTP, storage, and network. See ADR 02. |
| Ubiquitous language | Shared vocabulary (this page) embedded in code names, docs, and UI so product and engineering stay aligned (Conway’s law). |
Deprecated and avoided terms
| Avoid | Use instead |
|---|---|
Vault / vault_id (public API) | Drive / drive_id |
| Row-level sharing | Content-level sharing |
| Microservices (for current gateway) | Modular monolith |
| Home base alone (ambiguous) | Substratum Cloud, SaaS, or cloud_connected + explain mesh if needed |
| ACL in user-visible UI | People, groups, who can access |
| Cloud alone | Hosting topology and/or mesh mode explicitly |
| Micro-frontend (MFE) | Modular frontend monolith (one SPA + libs/* packages) |
| Micro-frontend host | Application shell (in-process layout + nav manifest) |
Acronyms (quick reference)
| Acronym | Expansion |
|---|---|
| ADR | Architecture Decision Record |
| ATProto | AT Protocol |
| CAR | Content Addressable aRchive (export format; ADR 29) |
| CID | Content Identifier |
| DID | Decentralized Identifier |
| DPoP | Demonstration of Proof-of-Possession |
| JWT | JSON Web Token (gateway session) |
| MST | Merkle Search Tree (AT Protocol repo commits) |
| OAuth | Open Authorization |
| PDS | Personal Data Server |
| PSK | Pre-Shared Key |
| RLS | Row-Level Security (Postgres catalog isolation) |
| SSE | Server-Sent Events (upload progress) |
| TUS | tus.io resumable upload protocol (ADR 26) |
For protocol-deep acronyms in a single ADR, see the local glossary sections in ADR 21, ADR 27, ADR 28, ADR 29, and ADR 30.