A practical way to make architectural intent explicit, reviewable, and durable.
Architectural Decision Records for Data Platforms
A practical way to make architectural intent explicit, reviewable, and durable.
Why ADRs matter in data platforms
Data architectures accumulate decisions. Some are explicit. Most are not.
Over time, this leads to familiar questions:
- Why is this modeled this way?
- Why do we parse SQL instead of treating it as text?
- Why is this rule enforced here but not elsewhere?
- Why is this query generated rather than handwritten?
Without a shared record, answers live in people’s heads — or are rediscovered repeatedly.
Architectural Decision Records (ADRs) provide a simple mechanism to capture why a decision was made, not just what was built.
In MDDE, ADRs became one of the most practical tools we adopted.
What an ADR is (and is not)
An ADR is:
- Short
- Focused
- Decision-oriented
It is not :
- A design document
- A requirements specification
- A historical narrative
An ADR answers one question:
Given a context, what decision did we make — and why?
The MDDE ADR format
We intentionally keep ADRs minimal.
ADR Template
Title
ADR-00X — Decision name
Context
What situation or problem triggered the decision?
Decision
What was decided?
Rationale
Why this option over the alternatives?
Consequences
What does this enable?
What does it intentionally restrict?
That’s it.
If it takes more than a page, it’s no longer an ADR.
Example 1 — SQL must be parsed, not trusted
ADR-001 — SQL must be parsed
Context
SQL was historically treated as opaque text, making comparison, validation, and systematic analysis difficult during migration and change.
Decision
All SQL is parsed into a structured representation before analysis, validation, or generation.
Rationale
Textual comparison obscures semantic equivalence and difference. Parsing makes intent explicit and comparable.
Consequences
- Enables normalization and deterministic generation
- Disallows opaque SQL blobs in the pipeline
Example 2 — Regression testing is mandatory for migrations
ADR-004 — Regression testing is required
Context
Confidence-based validation proved insufficient for large-scale platform change.
Decision
All migrations must include systematic regression testing at structural and result levels.
Rationale
Regression testing exposes implicit assumptions and semantic differences early.
Consequences
- Increases upfront effort
- Reduces downstream uncertainty
ADRs as living architecture
ADRs are not static.
In MDDE:
- ADRs evolve as understanding improves
- Superseded decisions are marked, not deleted
- New ADRs reference earlier ones
This creates an architectural narrative without requiring a central authority or long documents.
Most importantly, ADRs scale.
You can add one decision at a time, exactly when it becomes necessary.
How we use ADRs in practice
ADRs are created:
- When a decision affects multiple components
- When a rule becomes enforceable
- When flexibility is intentionally removed
- When behavior must remain stable over time
They are referenced:
- In code comments
- In rule definitions
- In generated documentation
- During reviews and onboarding
ADRs become the connective tissue between intent, implementation, and evolution.
Start small
You don’t need dozens of ADRs.
Start with:
- One decision that keeps coming up in discussion
- One rule that people question
- One behavior that must not change accidentally
Write it down.
That alone improves architectural clarity.
What’s next
In the next practical articles, I’ll share:
- How guidelines become executable rules
- A minimal MDDE project structure
- Sample code for parsing, validation, and generation
- How ADRs connect directly to implementation
All focused on turning architectural intent into concrete, reviewable artifacts.