ADR 04: Sidecar Design

Status: Accepted Date: 2026-04-09

The Substratum Sidecar is the local agent that runs on the user's machine. It is responsible for joining the private swarm, syncing data, and providing a local gateway.

Headless First

The Sidecar is built as a headless daemon (CLI binary) first. It exposes a local HTTP API (e.g., localhost:8080/ipfs/{cid}) that local applications (or the user's browser) can hit.

Why Headless?

• Flexibility: Power users, developers, and home-server enthusiasts (e.g., running on a Raspberry Pi or Unraid) will want to run the Sidecar as a Docker container or a background systemd service without a GUI.
• Simplicity: Building the core syncing and local gateway logic as a CLI tool makes it much easier to test and deploy.
• The GUI: The GUI (whether built with Tauri, Electron, or a local web server) should simply be a control panel that talks to the local CLI daemon's API to show sync status and configure settings.

Ports and Adapters Integration

The Sidecar uses the Ports and Adapters architecture to support CLI, REST, RPC, and GUI without rewriting the core engine.

• Primary Adapters:
  • Adapter: CLI (Translates terminal commands into ManageVaults calls).
  • Adapter: REST API (Translates HTTP GET /ipfs/{cid} into ServeContent calls).
  • Adapter: RPC/gRPC (For a future GUI to talk to the daemon efficiently).
• Secondary Adapters:
  • Adapter: libp2p/Bitswap (Implements the Network port).
  • Adapter: FlatFile/RocksDB (Implements the Storage port).

By building the Sidecar as a headless daemon with strict interfaces, we ensure that adding a GUI or a new API protocol is a trivial addition of a new adapter, not a rewrite of the core logic.