Architecture Decision Records

Architecture Decision Records (ADRs) capture the why behind structural choices in Itstabyl: the forces in tension, the option taken, the alternatives rejected, and the follow-on commitments the decision creates.

ADRs are short, immutable, and dated. When an earlier ADR is replaced, the original is preserved with a Superseded status and a back-reference to the new record.

Format

Itstabyl uses a lightweight Nygard-style ADR format:

ADR-NNN — <decision title>
Status:        Proposed | Accepted | Superseded by ADR-MMM
Date:          YYYY-MM-DD
Context:       The forces in tension at the time of the decision.
Decision:      What we chose, in one paragraph.
Consequences:  Positive, negative, and follow-on commitments.

Index

The customer-facing ADR set is intentionally narrow — it covers decisions that bind the contract Itstabyl makes with the outside world (data shapes, public APIs, security boundaries). Internal-only decisions live in the engineering corpus and are not republished here.

| ID | Decision | Status | | ------- | ----------------------------------------------------------------- | -------- | | ADR-001 | Engine-pipeline orchestration boundary (E1 – E12) | Accepted | | ADR-002 | 10-axis Survivability Vector — fixed dimensionality and ordering | Accepted | | ADR-003 | LRS weighting policy and per-version recalibration cadence | Accepted | | ADR-004 | Vendor lock-in matrix scoring methodology | Accepted | | ADR-005 | Storage of pipeline outputs as JSONB columns vs. event sourcing | Accepted | | ADR-006 | CSP nonce strategy & choice of @next/mdx over Nextra for docs | Accepted | | ADR-007 | Vendor circuit breakers — fail-fast 503 with Retry-After | Accepted | | ADR-008 | Hashed-IP retention policy for warning acknowledgments | Accepted | | ADR-009 | Per-assessment pricing model (no seat-based subscription) | Accepted |

Each ADR above is a long-form record covering context, decision, and consequences. The customer-facing set is intentionally narrow — internal implementation ADRs live in the private AURA/ spec corpus, which auditors and prospective enterprise customers can request under NDA.

Why this is a stable list

Each entry above corresponds to an invariant enforced by the test suite. Changing one of these decisions requires:

  1. A new ADR superseding the old one,
  2. A code change that updates the relevant invariant test, and
  3. A migration plan for any persisted data shape affected by the change.

This three-part discipline is why the customer-visible API and report shapes are stable across releases and why every release announcement on the changelog cites the ADRs touched.