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
| Activity | Design — Decide how to build it. Capture trade-offs, contracts, and architecture decisions. |
|---|---|
| Default location | docs/helix/02-design/adr/ADR-{number}-{decision-name}.md |
| Requires | None |
| Enables | None |
| Informs | Solution Design Technical Design |
| HELIX documents | docs/helix/02-design/adr/ADR-002-tracker-write-safety-model.md |
| Generation prompt | Show the full generation prompt |
| Template | Show the template structure |
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"
}
]
}