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
2026-07-16 : 0028 — TypeScript architecture boundaries
2026-10-13 : 0029 — Digest auth via challenge-retry
2026-10-18 : 0030 — MCP stdio transport
2026-10-18 : 0031 — MCP OAuth 2.1 in Electron main
2026-10-25 : 0032 — Agent harness: evals first, hook-enforced rules
2026-10-25 : 0033 — Evals gate harness changes
2026-10-26 : 0034 — Shared Postman parser and _postman sidecar
2026-10-30 : 0035 — Review depth tiers, verification vote and REVIEW.md
: 0036 — NTLM as a desktop-only fetcher handshake
2026-10-31 : 0037 — Agent Lab: suites, runtime and telemetry
: 0038 — CLI judges and dataset evals
: 0039 — One variable token grammar
: 0040 — Random install ID for Release Health
2026-11-03 : 0041 — Desktop MCP control server
: 0042 — Rate-limit principal and trusted proxy
2026-11-07 : 0043 — Electron Git runtime hardening
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. Hosting superseded by ADR 0041.
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.
0028 — TypeScript architecture boundariesExecutable source-zone directions, runtime-cycle detection, and non-growing file-size and source-pattern ratchets enforced by npm run architecture:check.
0029 — Digest auth via challenge-retryDigest answered once in the shared HTTP core: no credentials before the 401, one same-origin retry sharing the redirect budget, secrets resolved at the wire.
0030 — MCP stdio transportLocal MCP servers spawned by the desktop main process without a shell, after a main-owned consent check on every launch (a native prompt unless a matching approval is remembered); allowlisted env; main kills the process on disconnect and quit.
0031 — MCP OAuth 2.1 in Electron mainMCP authorization (PRM discovery, DCR, PKCE, resource indicators) driven from the main process: system browser + loopback redirect, guarded OAuth fetches, tokens only in internal-scope keychain handles.
0032 — Agent harness: evals first, hook-enforced rulesSeam-bug evals before restructuring reviewer agents; delivery rules enforced by hooks and a report verifier instead of prose; slim CLAUDE.md/AGENTS.md with detail loaded on demand; review of the combined diff.
0033 — Evals gate harness changesReviewer topology, skill routing and the vendored-skill set change only with a before/after eval on the same harness: train/test split, per-case flips, history-free runs, escaped defects become cases.
0034 — Shared Postman parser and _postman sidecarOne SDK-free Postman parser in shared/ for renderer and CLI; dropped or approximated constructs are reported and kept raw in a store-scoped _postman sidecar (stripped on edit, redacted on export and handle conversion); OAuth1 and NTLM map 1:1. v3 is the default export; v2.1 stays as the Newman option.
0035 — Review depth tiers, verification vote and REVIEW.mdThe code-review skill picks Quick/Standard/Deep from the diff, verifies Important findings with independent voters before posting, tags findings Important / Nit / Pre-existing, caps nits and rounds, and loads a code-owner REVIEW.md; sub-agents read briefs from disk instead of receiving pasted context.
0036 — NTLM as a desktop-only fetcher handshakeNTLM authenticates a connection, so the type 1 → 2 → 3 handshake runs inside one Electron fetcher call on a single pinned HTTP/1.1 socket, origin-bound and credential-free until the challenge; web and self-host don't send it and the CLI refuses it.
0037 — Agent Lab: suites, runtime and telemetrySuites are portable data and runtimes own every network and credential binding; one shared runner with provider and tool-source adapters; only read tools run unattended, CI needs operator assertions; QuickJS sandbox and A2A tool sources; one RunEngine lifecycle for evals, agents and Arena; metadata-only telemetry.
0038 — CLI judges and dataset evalsReverses the CLI judge refusal for dataset evals: restura eval run executes exported restura.eval files on the shared eval core with env credentials, cost budgets across model and judge calls, and a per-eval pass threshold as the exit code; http-exec and Arena stay desktop-only.
0039 — One variable token grammarOne {{name}} grammar in shared/variables/tokens.ts read by every resolver, the highlighter and both secret matchers; unknown non-plain text is not reported as unresolved; the app keeps its definition-order chaining while the CLI and streaming sends stay single pass.
0040 — Random install ID for Release HealthDesktop Release Health sessions carry a random, non-derived install ID so Sentry can count installs. Errors never carry it, the same opt-out deletes it, and the release smoke test reports as its own environment.
0041 — Desktop MCP control serverThe running desktop app hosts a loopback MCP server whose tools run in the renderer against the real stores; Restura --mcp-server is a stdio relay. Consent per collection and environment, in-app approvals, user-typed secrets and redaction.
0042 — Rate-limit principal and trusted proxyThe rate-limit bucket is client IP plus the principal the auth middleware verified; self-host Node keys on the socket peer unless TRUST_PROXY=true.
0043 — Electron Git runtime hardeningDesktop Git runs with repo hooks and diff.external disabled and safe.bareRepository=explicit, and the renderer file API refuses paths inside .git/, so an untrusted collection repo or a compromised renderer cannot make main execute a program.
Related
Section titled “Related”- Architecture overview — the three-backend model these ADRs decide on.
- Shared protocol layer — the deep dive behind ADR 0001.
- Security model — the consolidated design behind ADR 0004 and ADR 0006.