Skip to content

Architecture Decision Record

Purpose

An ADR is the single-decision record for architecture-significant choices. Its unique job is to preserve why a decision was made, what alternatives were considered, and what tradeoffs were accepted.

ADRs are not architecture documents. Architecture owns the overall structural model. ADRs are not solution designs or technical designs; those apply accepted decisions to narrower scopes. ADRs are not meeting notes; keep only the context that changes how future readers should evaluate the decision.

Example

Show a worked example of this artifact
---
ddx:
  id: example.adr.depositmatch.postgresql-system-of-record
  authoring:
    home: repo
  depends_on:
    - example.architecture.depositmatch
---

# ADR-001: Use PostgreSQL as the System of Record

## Problem

DepositMatch must keep imports, source rows, match suggestions, reviewer decisions, exceptions, and audit evidence consistent with each other (PRD P0-1, P0-3, P0-4, P0-5). v1 starts from CSV imports with no external accounting APIs or bank feeds, so auditability and a fast pilot matter more than independent scaling of each data type.

## Decision

We will use PostgreSQL 16 as the single system of record for all DepositMatch v1 data, including audit-log records. Uploaded CSV originals stay in encrypted object storage; PostgreSQL holds their metadata and the normalized rows.

## Why We Chose This

### Over a document database
Flexible import payloads and fewer joins do not outweigh weaker relational integrity across invoices, deposits, matches, and corrections. Audit consistency is the point of the product.

### Over a separate event store plus read models
Event replay is attractive for audit history, but it costs more infrastructure and slows the pilot. Revisit if audit replay needs outgrow relational history.

## Consequences

**Good**: Imports, matches, exceptions, and audit records commit atomically and can be queried together.

**Trade-offs**: High-volume matching or analytics may later need read replicas or separate derived stores. Keep analytics derived and keep raw financial fields out of analytics events.

**Drift signals to watch**: An accepted match without source-row evidence. A partial import commit. A second store quietly becoming a source of truth.

## Concern Impact

- **Affects concerns**: Reinforces `reviewer-auditability`, `csv-import-integrity`, and `financial-data-security`. No practice override.

Reference

ActivityDesign — Decide how to build it. Capture trade-offs, contracts, and architecture decisions.
Default locationdocs/helix/02-design/adr/ADR-{number}-{decision-name}.md
RequiresNone
EnablesNone
InformsSolution Design
Technical Design
HELIX documentsdocs/helix/02-design/adr/ADR-002-tracker-write-safety-model.md
Generation prompt
Show the full generation prompt
# Architecture Decision Record (ADR) Generation Prompt

Write a compact ADR that captures one architecture-significant decision, the
alternatives, and the consequences.

## Storage Location

Store at: `docs/helix/02-design/adr/ADR-NNN-<decision-name>.md` — **one decision
per file**. Naming is canonical and checkable: uppercase `ADR`, a **zero-padded
3-digit** sequential number, then a kebab-case decision name (e.g.
`ADR-001-modular-monolith.md`, `ADR-007-auth-tenant-isolation.md`). Do **not** use
lowercase `adr-` or 4-digit numbers, and do **not** lump multiple decisions into
one record. reconcile-alignment flags non-canonical names and lumped ADRs.

## Purpose

An ADR is the **single-decision record** for architecture-significant choices.
Its unique job is to preserve why a decision was made, what alternatives were
considered, and what tradeoffs were accepted.

ADRs are not architecture documents. Architecture owns the overall structural
model. ADRs are not solution designs or technical designs; those apply accepted
decisions to narrower scopes. ADRs are not meeting notes; keep only the context
that changes how future readers should evaluate the decision.

## Reference Anchors

Use these local resource summaries as grounding:

- `docs/resources/adr-github-organization.md` grounds ADRs as
  single-decision records with rationale, tradeoffs, and consequences.
- `docs/resources/google-cloud-architecture-decision-records.md` grounds ADR
  traceability to architecture evolution, code, and infrastructure context.

## Focus
- State the problem and decision plainly. If the operator has not stated the
  intent behind the decision, confirm it before drafting (see `modes/design.md`).
- State the chosen direction without claiming implementation completion.
  Record implementation gaps and observed results in the relevant plan,
  selected work item, or factual report; do not add progress banners here.
- For each alternative, say why this choice beats it; keep it brief and honest.
- Name drift signals only when they would reveal the decision being abandoned.
- Add the optional **Assumptions** section when the decision rests on facts
  not yet proven, each with what would invalidate it. A provisional-risk note
  belongs here.
- Add the optional **Validation** section when the decision should be tested
  with real use (common for interface decisions). Result is `not tested`,
  `tested` or `refuted`; Evidence cites what settled it: a study's research
  plan, the metrics dashboard, or an experiment. Update it in place when the
  evidence arrives; a refuted decision is rewritten, not appended to.
- Omit dates, status, deciders, and risk or metric tables; git and the tracker hold them.
- Use one ADR per decision. If the decision has independent parts, split it.
- Keep one current record of the chosen direction and useful rationale. When
  the decision changes, even to a reversal, rewrite it in place and move the
  replaced option to the alternatives with the reason it lost. Do not add a
  change log; source control keeps the history.
- **Do not accept a decision whose design-defining facts are assumed.** A
  decision's design-defining facts (API shape, data model, pricing/cost
  semantics, security/permissions, operational guarantees, or work decomposition)
  must be **evidenced** — by an operator statement, a governing artifact, an
  existing implementation, a docs/API proof, or a completed spike — not by model
  familiarity, and not because a mechanism was picked or a provider named.
  Choosing a provider and deferring its live integration does **not** evidence the
  decision. If a design-defining fact is assumed, the ADR must cite **spike
  evidence**, record a **blocked-spike rationale**, or carry an explicit
  **provisional-risk** note (what is assumed, what could invalidate it, and that
  the assumption is reversible/non-blocking). See the anti-reframe check in
  `workflows/references/concern-resolution.md` (step 3a). An operator-marked
  "spike/unknown" may not be accepted as a settled ADR without **spike evidence, a
  blocked-spike rationale, or an explicit provisional-risk note**. A
  **business/product** unknown a technical spike can't answer (e.g. a pricing
  model) → record **guidance-needed** or a blocked spike rather than forcing a
  technical spike or accepting an assumed decision.

## Boundary Test

| If you are writing... | Put it in... |
|---|---|
| Overall system structure or deployment topology | Architecture |
| One architecture-significant decision and rationale | ADR |
| Feature-specific design applying accepted architecture | Solution Design |
| Story-level component or code plan | Technical Design |
| API schema, event payload, or file format | Contract |
| Work steps or sequencing | Implementation Plan |

## Completion Criteria
- The decision is unambiguous.
- Alternatives are compared clearly.
- Consequences are explicit.
- The decision states current working intent; no lifecycle stamp is required.
- Drift signals are concrete when the decision has uncertainty.
Template
Show the template structure
---
ddx:
  id: ADR-XXX
  authoring:
    home: repo
---

# ADR-NNN: [Title]

## Problem

[What constraint or tension prompted this decision? What's broken or at risk?]

## Decision

We will [decision statement].

## Why We Chose This

### Over [Alternative 1]
[Why this beats the alternative — what matters more: trade-off, risk, intent.]

### Over [Alternative 2]
[Why this beats the alternative — what matters more: trade-off, risk, intent.]

## Consequences

**Good**: [Outcomes that enable the PRD / reduce risk / unblock work]

**Trade-offs**: [What we give up, defer, or constrain]

**Drift signals to watch**: [Anti-patterns in review that signal this decision is being abandoned]

## Assumptions

[Optional. What the decision takes as true without proof yet, and what would
show it false. Delete if none.]

- [Assumption]: [What would invalidate it]

## Validation

[Optional. Whether the decision has been tested with real use. Delete if the
decision needs no validation.]

**Result**: [not tested | tested | refuted]
**Evidence**: [The study's research plan, the metrics dashboard, or the experiment that settled it]

## Concern Impact

- **Override / deviation**: [Does this ADR override or deviate from a library concern constraint or practice? If so, add this ADR to Project Overrides in `docs/helix/01-frame/concerns.md`. Selecting a concern needs no ADR; `concerns.md` records it.]
- **No concern impact**: [Delete if not relevant.]
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifact-types/design/adr.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:45d1f5a5…72453332

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifact-types/design/adr/",
        "digest": {
          "alg": "sha256",
          "value": "45d1f5a5e830f9086a50c542729ff49a77ef5b4badc22894a1cc1f8072453332"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "8wr3PJQ8SJg3Pbz_1gPf6_3o3637jraWYSIX3_ep4ILC1_33f-a4QNi2i2UhLMEeHuMA6r2RU1-Gg-7VLAE_DA",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}