Skip to main content

4DDR vs Traditional ADRs

While 4D Decision Records (4DDRs) build upon the foundation of Architecture Decision Records (ADRs), they extend the concept significantly to better serve modern software development practices.

Side-by-Side Comparison​

AspectTraditional ADR4DDR
ScopeArchitectural decisions onlyAll decisions across 4 phases
TimingDesign phase primarilyThroughout entire project lifecycle
Frequency10-50 per projectPotentially 100+ per project
GranularityHigh-level architectureAny decision affecting constraints
AudienceSenior developers, architectsEntire team including PM, QA, DevOps
FormatOften lengthy documentsOne-screen, template-driven
LifecycleCreate once, rarely updateMutable, evolves with project
Tool IntegrationManual documentationLLM-ready, structured format

Traditional ADR Structure​

A typical ADR follows this format:

# ADR-001: Use PostgreSQL for Data Storage

## Status
Accepted

## Context
We need to choose a database for our e-commerce platform.
The system needs to handle transactions, product catalogs,
and user data with strong consistency requirements.

## Decision
We will use PostgreSQL as our primary database.

## Consequences
Positive:
- Strong ACID compliance
- Rich SQL feature set
- Good community support

Negative:
- Requires specialized knowledge
- Higher resource usage than NoSQL
- Scaling complexity

4DDR Structure​

The same decision as a 4DDR:

Status: Accepted
Phase: Design
Decision: Use PostgreSQL for primary data storage
Context: E-commerce platform needs ACID transactions, complex queries
Consequences: Requires PostgreSQL expertise, higher resource usage
Alternatives: MongoDB, MySQL, SQLite
Author: Database Team
Date: 2025-07-22
Links: ["PR #456", "Performance Analysis Doc"]

Key Differences​

1. Brevity vs Depth​

Traditional ADR:

  • Often 1-3 pages long
  • Detailed context and reasoning
  • Extensive consequences analysis
  • Formal decision-making process

4DDR:

  • Fits on one screen
  • Structured fields for quick scanning
  • Essential information only
  • Optimized for frequent creation

2. Phase Coverage​

Traditional ADR:

4DDR:

3. Decision Types​

Traditional ADR Examples:

  • Should we use microservices or monolith?
  • Which database technology to adopt?
  • What authentication strategy to implement?
  • How should we structure our APIs?

4DDR Examples:

  • Discover: Which user research method to use?
  • Design: API authentication strategy
  • Develop: Code review process
  • Deploy: Blue-green vs rolling deployment

4. Evolution and Maintenance​

Traditional ADR:

  • Status changes: Proposed → Accepted → Superseded
  • Rarely updated after acceptance
  • New ADR created to supersede old ones
  • Historical record maintained

4DDR:

  • More fluid status transitions
  • Can be updated as context changes
  • Living documents that evolve
  • Automated archival policies

When to Use Which Approach​

Use Traditional ADRs When:​

  • ✅ Making major architectural decisions
  • ✅ Decisions require extensive justification
  • ✅ Compliance requirements need detailed documentation
  • ✅ Team has time for lengthy analysis
  • ✅ Decisions are infrequent and high-impact

Use 4DDRs When:​

  • ✅ Following GISE methodology
  • ✅ Making decisions across all project phases
  • ✅ Need quick decision capture
  • ✅ Working with AI-assisted development
  • ✅ Want consistent decision format
  • ✅ Team makes frequent, iterative decisions

Hybrid Approach​

Many teams successfully combine both approaches:

  • 4DDRs for day-to-day decisions across all phases
  • Traditional ADRs for major architectural choices that need extensive analysis
  • Cross-references between related 4DDRs and ADRs

Example hybrid structure:

/decisions/
  adr/
    001-microservices-architecture.md
    002-authentication-strategy.md
  4ddr/
    0001-user-research-method.md
    0002-frontend-framework.md
    0003-testing-strategy.md
    0004-deployment-process.md

Migration Path​

If you're currently using traditional ADRs and want to adopt 4DDRs:

Phase 1: Addition​

  • Keep existing ADRs unchanged
  • Start creating 4DDRs for new decisions
  • Cross-reference between ADRs and 4DDRs

Phase 2: Integration​

  • Convert high-frequency ADRs to 4DDR format
  • Establish clear criteria for ADR vs 4DDR usage
  • Update team processes to include 4DDR creation

Phase 3: Standardization​

  • Migrate remaining ADRs to 4DDR format where appropriate
  • Establish 4DDR as primary decision documentation
  • Maintain ADRs only for decisions requiring extensive analysis

Tools and Automation​

Traditional ADR Tools:​

4DDR Tools:​

  • Template generators
  • YAML validation
  • Git hooks for automation
  • LLM integration for draft generation
  • Export to databases for analytics

Conclusion​

4DDRs represent an evolution of the ADR concept, optimized for:

  • Modern development practices (agile, continuous delivery)
  • AI-assisted development workflows
  • Cross-functional teams with diverse stakeholders
  • Rapid iteration and frequent decision-making

While traditional ADRs remain valuable for major architectural decisions requiring extensive analysis, 4DDRs provide a lightweight, structured approach to capturing the multitude of decisions that shape modern software projects across all phases of development.