Substratum.cloud

Appearance

ADR 10: Repository Structure and Workspace Tooling ​

Status: Accepted Date: 2026-04-10 Updated: 2026-04-24

Context ​

We need to structure the Substratum codebase to support a polyglot environment (Rust for the backend/P2P nodes, TypeScript for the frontend) while strictly enforcing the Single Responsibility Principle (SRP) and our Ports and Adapters architecture.

Specifically, the cloud infrastructure (the Gateway) has four distinct responsibilities defined in the Technical Specification: Ingress, Auth, Resolution, and Retrieval. Combining these into a single monolithic crate would violate SRP and make code reuse difficult for the local home-base daemon. Furthermore, the UI needs to be decoupled into reusable components.

Decision ​

We will use a Polyglot Monorepo orchestrated by Nx (for task running and caching) and Cargo (for Rust workspace management).

The repository will be structured as follows:

1. Applications (apps/) ​

  • apps/file-explorer: The consumer-facing web application (Mithril.js). It acts as the user's sovereign file manager and AT Proto authorization hub.
  • apps/gateway: The cloud executable deployed to DigitalOcean. It is a thin dependency-injection layer that wires together the 4 pillar crates (below) to serve the API and participate in the P2P swarm.
  • apps/home-base: The user's local daemon (Rust). It runs a local libp2p node, syncs data, and exposes a localhost gateway.

2. Frontend Libraries (libs/) ​

  • libs/ui-kit: Pure, state-free Mithril.js components (buttons, modals).
  • libs/api-client: Auto-generated TypeScript client for communicating with the Gateway API.

3. Rust Crates (crates/) ​

The Gateway's responsibilities are split into 4 distinct pillar crates, anchored by a common core:

  • crates/core (The Anchor): Shared domain logic, types (PassportReceipt, did:plc), and pure math (Swarm PSK generation). Must be WASM-compatible.
  • crates/ingress (The Front Door): Axum HTTP routing, rate limiting, header parsing, and the domain-driven API request/response DTOs (Data Transfer Objects) with OpenAPI schemas.
  • crates/auth (The Bouncer): AT Proto OAuth client and JWT verification.
  • crates/resolution (The Map): SeaORM database queries mapping CIDs to DIDs and enforcing ACLs.
  • crates/retrieval (The Fetcher): The rust-libp2p swarm, Bitswap protocol, and S3/Spaces client for fetching actual bytes.

Consequences ​

  • Positive:
    • Strict SRP: Each crate and application has exactly one reason to change.
    • Code Reuse: The home-base application can reuse the core and retrieval crates without needing to compile the resolution (PostgreSQL) crate.
    • UI Isolation: The file-explorer is decoupled from its visual language (ui-kit), allowing future apps (like a desktop GUI) to share the same design system.
    • Build Efficiency: Nx provides intelligent caching, only rebuilding the specific apps/crates that have changed.
  • Negative:
    • Tooling Complexity: Requires configuring Nx plugins to properly understand and cache Cargo workspaces.
    • Crate Boundary Overhead: Developers must carefully manage dependencies between the 4 pillar crates to avoid circular references.