peopleanalyst

Tools · Software engineering

Architecture Decision Record

Describe a decision — get a clean Architecture Decision Record (Nygard form).

How it works

Corpus-grounded (software-engineering cluster). Produces the standard ADR — title, status, context/forces, the decision, options considered with pros/cons, and consequences (positive + negative) — so the why survives the people.

You bring

{ decision, cluster? }

You get

{ decision_summary, title, status, context, decision, options_considered[]{option, pros[], cons[]}, consequences{positive[], negative[]}, riskiest_assumptions[], grounded_in, provenance }

Use it for

See it work

example output

Decision: "Should we adopt server-sent events or WebSockets for the live dashboard?" — small team, read-heavy, bursty updates.

ADR-014: Use Server-Sent Events for the live dashboard feed

Status: Accepted · Date: 2026-06-27 · Deciders: Platform team

Context

The live dashboard pushes metric updates to ~200 concurrent viewers. Traffic is read-heavy and one-directional (server → client); updates are bursty (0–30/min). The team is small (3 engineers) and the stack is already behind a standard HTTP/2 reverse proxy. We need low operational overhead and graceful reconnection more than we need bidirectional, low-latency messaging.

Options considered

  1. WebSockets — full duplex, lowest latency. Cost: a separate connection-upgrade path, sticky-session/load-balancer config, manual heartbeat + reconnection logic, and an extra moving part to operate.
  2. Server-Sent Events (SSE) — one-directional server push over plain HTTP. Built-in auto-reconnect and event IDs; works through the existing proxy with no upgrade handshake. Cost: no client→server channel (fine — we already have REST for writes) and a per-connection limit under HTTP/1.1 (moot under our HTTP/2 proxy).
  3. Short-polling — simplest, but wasteful at this viewer count and adds visible latency.

Decision

Adopt SSE for the dashboard feed. The data flow is one-directional, so WebSockets' duplex capability is unused complexity; SSE's built-in reconnection + event-ID resume directly serve our "bursty + must survive flaky networks" requirement at near-zero operational cost.

Consequences

  • Positive: no LB/sticky-session changes; auto-reconnect for free; writes stay on the existing REST path; one fewer protocol to operate.
  • Negative / watch-for: if a future feature needs client→server streaming (e.g. collaborative cursors), revisit — SSE won't cover it. Cap concurrent connections per instance and confirm the proxy doesn't buffer the event stream.
  • Revisit if: concurrent viewers exceed ~10k per instance, or a bidirectional realtime feature lands.

Run it now

Write an ADR

Turn a decision into an Architecture Decision Record — context, the decision, the options considered (pros/cons), and the consequences (good and bad).

Prefer code? Call it over the API or hand it to your AI agent via MCP — POST /api/bicycle/architecture-decision-record · write_adr. API & agent access →

← All tools