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
  2026-05-08 : 0001 — Shared protocol layer
  2026-05-09 : 0002 — Multi-tab store
             : 0003 — Streaming + HTTP/2
             : 0004 — Security hardening
             : 0005 — CLI runner
  2026-05-16 : 0006 — Connection + DNS hardening
  2026-05-27 : 0007 — SecretRef pattern

0001 — Shared protocol layer One implementation per protocol (HTTP, gRPC, MCP, SSE), three thin Fetcher adapters. The architectural keystone.

0002 — Multi-tab store The request state model — tabs[] + activeTabId — and why it replaced the previous single-active store.

0003 — Streaming and HTTP/2 How server-streaming gRPC, SSE, and chunked HTTP are handled across Worker, Node, and Electron.

0004 — Security hardening SSRF guards, keychain integration, QuickJS sandbox, wire-level signing — the consolidated security design.

0005 — CLI runner The @restura/cli executor architecture and the JUnit / HTML / JSON reporter design.

0006 — Connection + DNS hardening Idempotent renderer-cleanup, walk-and-dispose helper, pre-flight DNS guard, connect-time IP pinning for ws/sse/grpc.

0007 — SecretRef pattern Handle-based secrets: plaintext never leaves the main process; renderer, Zustand, and exports only see SecretRef handles.