Skip to content
Restura Docs

Architecture Decision Records

Architecture Decision Records capture significant design choices, the alternatives considered, and the reasoning. They’re the single best resource if you want to understand why the code is shaped the way it is.

timeline
  title Restura ADR timeline
  2025-11-05 : 0001 — Shared protocol layer
  2025-11-12 : 0002 — Multi-tab store
             : 0003 — Streaming + HTTP/2
             : 0004 — Security hardening
             : 0005 — CLI runner
  2025-12-03 : 0006 — Connection + DNS hardening
  2025-12-17 : 0007 — SecretRef pattern
  2026-01-14 : 0008 — OpenCollection native format
             : 0009 — Shared Hono app factory
  2026-02-04 : 0010 — AI assistant architecture
             : 0011 — Restura as an MCP server
  2026-02-25 : 0012 — Capability matrix source of truth
             : 0013 — Hash routing
  2026-03-18 : 0014 — Zustand persistence
             : 0015 — QuickJS script sandbox
  2026-04-08 : 0016 — Wire-level auth signing
             : 0017 — Runtime platform detection
  2026-04-29 : 0018 — Rate limiting strategy
             : 0019 — Response viewer architecture
  2026-05-20 : 0020 — AI Lab eval workbench
  2026-06-10 : 0021 — Maintenance harness
  2026-06-17 : 0022 — gRPC over ConnectRPC
  2026-06-24 : 0023 — AI Lab http-exec
  2026-06-28 : 0024 — Browser capture extension
  2026-06-29 : 0025 — VS Code extension
  2026-07-02 : 0026 — Electron CSP + permission hardening
  2026-07-03 : 0027 — Telemetry + privacy-preserving usage
0001 — Shared protocol layerOne implementation per protocol (HTTP, gRPC, MCP, SSE), three thin Fetcher adapters. The architectural keystone.
0002 — Multi-tab storeThe request state model — tabs[] + activeTabId — and why it replaced the previous single-active store.
0003 — Streaming and HTTP/2How server-streaming gRPC, SSE, and chunked HTTP are handled across Worker, Node, and Electron.
0004 — Security hardeningSSRF guards, keychain integration, QuickJS sandbox, wire-level signing — the consolidated security design.
0005 — CLI runnerThe restura-cli executor architecture and the JUnit / HTML / JSON reporter design.
0006 — Connection + DNS hardeningIdempotent renderer-cleanup, walk-and-dispose helper, pre-flight DNS guard, connect-time IP pinning for ws/sse/grpc.
0007 — SecretRef patternHandle-based secrets: plaintext never leaves the main process; renderer, Zustand, and exports only see SecretRef handles.
0008 — OpenCollection native formatA vendor-neutral, round-trippable collection format with JSON-Schema-generated types and a CI drift gate.
0009 — Shared Hono app factoryOne createApp() reused by the Cloudflare Worker and the self-hosted Node server, with platform-specific adapters.
0010 — AI assistant architectureElectron-first, provider-agnostic chat; context and secrets redacted before anything leaves the machine.
0011 — Restura as an MCP serverRestura as an MCP server: pure tool dispatch, consent gating, and SecretRef redaction on every response.
0012 — Capability matrix source of truthcapabilities.ts drives UI badges, the generated matrix doc, and a CI gate that fails on drift.
0013 — Hash routingcreateHashRouter so the identical SPA build runs under both https:// (Pages) and file:// (Electron).
0014 — Zustand persistenceOne persist pattern; Dexie on web, encrypted secure-storage on desktop, Zod-validated on rehydrate.
0015 — QuickJS script sandboxUser scripts run in a capability-gated WASM VM; the sandbox — not source inspection — is the boundary.
0016 — Wire-level auth signingSigV4 / OAuth1 / WSSE sign on the backend after the body is built, so signatures match the exact upstream bytes.
0017 — Runtime platform detectionisElectron() picks IPC vs HTTP transport from a single bundle, with the platform seam confined to executors.
0018 — Rate limiting strategyIndependent throttling at each boundary: an internet-facing Worker limiter and per-channel IPC limiters.
0019 — Response viewer architectureMonaco for finite bodies; a 5000-event capped incremental viewer for streams to stay memory-bounded.
0020 — AI Lab eval workbenchDesktop-only prompt/model testing: dataset evals, LLM-as-judge, and a loopback-only SSRF carve-out for local runtimes.
0021 — Maintenance harnessClaude Code tooling for production-grade upkeep: type-check:all closes the renderer-only gap, plus verify/maintain skill, review subagents, and a docs-parity steward.
0022 — gRPC over ConnectRPCOne ConnectRPC stack across web and desktop: Connect protocol on web, native gRPC over connect-node on desktop, one runtime descriptor registry. Replaces Connect-Web + grpc-js.
0023 — AI Lab http-execScoring AI-generated requests by executing them through the real request executor — inheriting the SSRF guard, redirects, and cookie jar instead of building a parallel client.
0024 — Browser capture extensionOne backend-agnostic capture core, thin adapters: a multi-protocol Chrome extension sharing the desktop app's audited redaction path, with a loopback-only Send-to-Desktop bridge.
0025 — VS Code extensionA focused editor integration for OpenCollection files — schema diagnostics, a Test Explorer that shells out to the restura CLI, and inline Send through the shared protocol core. No re-implemented execution or assertions.
0026 — Electron CSP + permission hardeningDefault-deny web permissions (single clipboard allowlist entry) and CSP object-src/worker-src pinning, with header/meta parity enforced by a structural test.
0027 — Telemetry + privacy-preserving usageThe minimum disclosed error and session-health signal: opt-out, scrubbed, non-identifying, and no new application-level web analytics.
Section titled “Related”
ResturaThe API client that speaks every protocol.
Built byDipjyoti MetiaGitHubMIT licensed