Architecture Decision Records

ADRs document significant technical decisions, the context that forced them, and the trade-offs accepted. They are permanent — if a decision changes, a new ADR supersedes the old one. Nothing is deleted or rewritten.

Index

#	Decision	Status
001	Load strategy terminology: full_refresh, incremental, historical, batch_replace	Active
002	Intraday refresh patterns for dynamic tables	Active
003	Build-time DAG generation (YAML → Python) over runtime dag-factory	Active
004	Metadata columns: RECORD_KEY, RECORD_HASH, BATCH_ID, LOADED_AT	Active
005	Three-tier stage configuration priority	Active
006	Bronze truncate + FORCE = TRUE for legacy pipelines	Active
007	Skip logic inside task functions, not in DAG structure	Active
008	Gold layer: fct_, dim_, agg_, rpt_	Active
009	Naming conventions — tables, DAGs, S3 paths, columns	Active
010	Rosters in CORE_DB, glossaries in client DB	Active
011	batch_replace for new pipelines, truncate_insert for legacy	Active
012	Documentation structure: docs/ as single source of truth	Active
—	Branching strategy	Active
—	Single account strategy	Active
—	Snowflake environments	Active
—	Naming conventions (legacy)	Superseded by 009
013 · Semantic layer choice (pending)	Semantic layer tool for product app analytics	Phase 0

How to write a new ADR

1. Open a Decision issue to work through options with the team
2. Pick the next number and create NNN-kebab-case-topic.md in this directory
3. Use this structure:

# ADR NNN — Title

## Status
Accepted  |  Proposed  |  Superseded by ADR NNN

## Context
What situation or constraint forced this decision? What would happen if we did nothing?

## Decision
What did we decide to do?

## Consequences
What gets easier? What gets harder? What do we give up?

## Options Considered
What else did we evaluate and why did we reject it?

1. Link the ADR from the Decision issue and close it
2. Update this index table

ADRs are append-only. Never rewrite history — future readers need to understand why decisions made sense at the time they were made.