ADR 11: Cross-Boundary Implementation Strategies

Status: Accepted Date: 2026-04-10

Context

With our Polyglot Monorepo (Rust/TypeScript) and dual-protocol backend (HTTP + P2P) defined, we must address three critical technical gaps before implementation:

1. Client-Side Cryptography: "Passport Receipts" require a cryptographic signature from the user's AT Proto private key. To maintain a Zero-Trust architecture, this key must never be sent to the cloud API.
2. API Type Safety: The Mithril.js UI needs to consume the Rust API without manually duplicating types or guessing endpoint structures.
3. Dual Event-Loop Concurrency: The api and home-base binaries must serve HTTP requests (Axum) while simultaneously managing a swarm of P2P TCP connections (libp2p) without blocking each other.

Decision

We will implement the following cross-boundary strategies:

1. The WASM Boundary (crates/core)

We will write the core domain logic (schemas, PSK generation, and cryptographic signing) in pure Rust with absolutely no I/O dependencies (no tokio, no std::fs).

• We will use wasm-bindgen to compile crates/core to WebAssembly (wasm32-unknown-unknown).
• The file-explorer UI will execute this WASM module in the browser's secure sandbox to sign Passport Receipts locally.
• The exact same Rust crate will be compiled natively for the home-base daemon, ensuring cryptographic consistency across platforms while guaranteeing the private key never leaves the client.

2. The API Contract (utoipa + orval)

We will automate the API contract between Rust and TypeScript using an OpenAPI pipeline orchestrated by Nx.

• Rust: We will use utoipa in the api crate to auto-generate an openapi.json specification directly from our Axum routes and SeaORM models.
• TypeScript: We will use orval to consume the openapi.json and generate a strongly-typed TypeScript client (libs/api-client). If the Rust database schema changes, the TypeScript build will fail if the UI is not updated.

3. The Actor Pattern (Axum + libp2p)

We will use the Actor Model (conceptually similar to Akka) to manage concurrency between the web server and the P2P swarm, utilizing tokio::sync::mpsc channels.

• The libp2p swarm will run in an isolated background task (the Actor) with its own infinite polling loop.
• The Axum HTTP handlers will communicate with the swarm by sending message enums (e.g., Command::FetchBlock(Cid, ResponderChannel)) to the Actor's mailbox.
• Axum will await the response via a oneshot channel. This prevents the high-throughput web server from freezing during long-running P2P network I/O.

Consequences

• Positive:
  • Maximum Security: The cloud infrastructure remains Zero-Trust; it never sees the user's private keys.
  • Developer Velocity: Automated OpenAPI generation eliminates manual type duplication and API drift.
  • Performance: The Actor Pattern ensures the HTTP server remains highly responsive even under heavy P2P network load.
• Negative:
  • WASM Constraints: Developers must be strictly disciplined to keep crates/core free of OS-level dependencies.
  • Build Complexity: Adds WASM compilation and OpenAPI generation steps to the Nx build pipeline.