Skip to content

Architecture overview

Restura ships from a single React renderer to web, desktop, and self-hosted targets. The transport layer is the only thing that differs — chosen at runtime by isElectron() in src/lib/shared/platform.ts.

Web — Cloudflare

SPA on Cloudflare Pages → https://api.restura.dev/api/... (VITE_WORKER_URL) → Cloudflare Worker (Hono) → upstream. The Worker is cross-origin to the SPA and allows it through a CORS allowlist (ALLOWED_ORIGIN). A relative /api/* is the dev and self-host shape. The self-hosted Node server serves SPA and API on one origin.

Self-hosted — Node + Docker

One Node process running the same Hono app that runs in the Worker. Serves both the SPA and /api/* on one port. Native WebSocket and CONNECT proxy adapters.

Desktop — Electron

SPA loaded via file:// → IPC over window.electron → Electron main process. HTTP uses undici; other native protocols use Node net/tls. Native capabilities (mTLS, SOCKS, Kafka, MQTT). The first renderer crash reloads; a second shows “Restura window crashed”.

The two HTTP backends (Cloudflare Worker and Node/Docker server) share a single Hono app via the createApp(deps) factory in worker/app.ts. Each entry supplies its own adapters for the platform-specific bits (CONNECT proxy, native WebSocket).

flowchart TB
  subgraph Web["Web target"]
    SPA1[React SPA<br/>Cloudflare Pages]
    SPA1 -->|fetch /api/*| W[Cloudflare Worker<br/>api.restura.dev]
  end
  subgraph SH["Self-hosted target"]
    SPA2[React SPA<br/>same bundle]
    SPA2 -->|/api/*| N[Node + Hono<br/>same createApp]
  end
  subgraph DT["Desktop target"]
    SPA3[React SPA<br/>file://]
    SPA3 -->|IPC| EM[Electron main]
  end
  W --> U[(upstream)]
  N --> U
  EM --> U

  classDef target fill:#7b6ef622,stroke:#7b6ef6,color:inherit;
  class Web,SH,DT target;

Each protocol (HTTP, gRPC, MCP, SSE, WebSocket, AI) is implemented once as a backend-agnostic orchestrator in shared/protocol/. Each backend supplies a thin Fetcher adapter — and that’s it. Everything else — SSRF validation, header sanitisation, body construction, response shape, gRPC status mapping, SSE / NDJSON parsing — lives in shared/protocol/ and runs identically across Worker, Node, and Electron.

flowchart TB
  SP["shared/protocol/<br/>{http,grpc,mcp,sse}-proxy.ts<br/><br/>validation · body · headers · response shape"]
  SP -->|Fetcher| W[worker/handlers/*<br/>globalThis.fetch]
  SP -->|Fetcher| E[electron/main/*-handler.ts<br/>undici / Node net]
  SP -->|Fetcher| C[cli<br/>undici]

  classDef core fill:#7b6ef6,stroke:#4f46e5,color:#fff;
  classDef adapter fill:#6366f122,stroke:#7b6ef6,color:#7b6ef6;
  class SP core;
  class W,E,C adapter;

See Shared protocol layer for the deep dive.

createHashRouter is used so the renderer works under both https:// (Pages) and file:// (Electron). There is no server-side routing.

All global state lives in Zustand stores with the persist middleware. Zod hydration checks run only for stores that wire a validator from src/lib/shared/store-validators.ts.

  • Web and desktop — src/lib/shared/dexie-storage.ts (IndexedDB via Dexie).
  • Desktop encryption — the Dexie key comes from ElectronSafeStorageKeyProvider in src/lib/shared/keyProvider.ts (Electron safeStorage → OS keychain). src/lib/shared/secure-storage.ts holds secret material only. Web uses PlaintextKeyProvider.

Secret-bearing fields use the SecretRef handle pattern — see ADR 0007 — so plaintext never enters the Zustand store, the persistence layer, or exported collections.

src/lib/shared/capabilities.ts is the single source of truth for what works on web vs. desktop. It feeds:

  • The “Desktop only” badges you see in the UI.
  • The auto-generated capability matrix.
  • The CI gate (npm run capabilities:check) that fails the build if the doc drifts from the code.

See docs/ARCHITECTURE.md on GitHub for the canonical source-of-truth for contributors.