| name | Architecture Decision Records |
| description | Create and maintain Architecture Decision Records (ADRs) in Confluence. Use when documenting technical decisions, architecture choices, technology selections, or when user mentions ADR, architecture decisions, technical choices, or design decisions. |
Architecture Decision Records (ADR)
Expert assistance for creating and maintaining Architecture Decision Records in Confluence.
When to Use This Skill
- Documenting architectural decisions
- Recording technology choices
- Explaining design decisions
- Creating technical decision logs
- User mentions: ADR, architecture, technical decision, design choice
What Are ADRs?
Architecture Decision Records document important architectural decisions made during a project:
Purpose
- Record context: Why the decision was needed
- Document options: What alternatives were considered
- Explain choice: Why this option was selected
- Note consequences: What are the trade-offs
Benefits
- Historical record of decisions
- Onboarding new team members
- Preventing decision revisitation
- Understanding system evolution
- Avoiding repeated mistakes
ADR Structure
Standard Template (Michael Nygard format)
# [Number]. [Title]
**Date**: YYYY-MM-DD
**Status**: [Proposed | Accepted | Deprecated | Superseded]
**Decision Makers**: [Names or team]
**Technical Story**: [Optional ticket/issue reference]
## Context
What is the issue we're seeing that is motivating this decision or change?
## Decision
What is the change that we're proposing and/or doing?
## Consequences
What becomes easier or more difficult to do because of this change?
### Positive
- List of positive consequences
### Negative
- List of negative consequences
- Known limitations
- Trade-offs
Example ADR
# 001. Use PostgreSQL for Primary Database
**Date**: 2024-01-15
**Status**: Accepted
**Decision Makers**: Engineering Team
**Technical Story**: PROJ-123
## Context
We need to select a database system for our new user management service. The service will:
- Handle up to 1M users initially, growing to 10M
- Require complex queries across multiple tables
- Need ACID compliance for user transactions
- Support full-text search on user profiles
- Integrate with our existing infrastructure
We evaluated several options:
- PostgreSQL
- MySQL
- MongoDB
- DynamoDB
## Decision
We will use PostgreSQL 15 as our primary database.
**Key factors in this decision:**
1. **ACID Compliance**: Strong guarantees for user data integrity
2. **Complex Queries**: Excellent support for JOINs and aggregations
3. **JSON Support**: Native JSONB for flexible schema evolution
4. **Full-Text Search**: Built-in search capabilities with tsvector
5. **Proven at Scale**: Used successfully by similar applications
6. **Team Expertise**: Team has 5+ years PostgreSQL experience
7. **Cost**: Open source with commercial support available
## Consequences
### Positive
- **Data Integrity**: ACID compliance ensures user data consistency
- **Query Flexibility**: Rich SQL support for complex reporting
- **Future-Proof**: JSON support allows schema evolution
- **Performance**: Excellent performance for our workload patterns
- **Ecosystem**: Vast ecosystem of tools and extensions
- **Monitoring**: Mature monitoring and debugging tools
- **Team Velocity**: Team can be productive immediately
### Negative
- **Scaling Complexity**: Horizontal scaling requires additional tooling (Citus)
- **Operational Overhead**: Requires database administration expertise
- **Backup Strategy**: Need to implement robust backup/recovery
- **Cloud Lock-in**: Managed PostgreSQL ties us to cloud provider
- **Migration Cost**: Future migration to different database would be expensive
### Mitigation Strategies
- Use connection pooling (PgBouncer) for connection management
- Implement read replicas for read scaling
- Regular backup testing and disaster recovery drills
- Database versioning with migration tools (Flyway)
- Monitor query performance with pg_stat_statements
### Alternatives Considered
**MySQL**:
- ✅ Similar performance and features
- ❌ Less sophisticated JSON support
- ❌ Team less experienced
**MongoDB**:
- ✅ Excellent horizontal scaling
- ❌ No ACID transactions (at the time)
- ❌ Weak JOIN support for complex queries
**DynamoDB**:
- ✅ Fully managed, auto-scaling
- ❌ Complex query limitations
- ❌ Higher cost at scale
- ❌ AWS lock-in
## Notes
This decision can be revisited if:
- Scale exceeds 50M users
- Query patterns change dramatically
- Team expertise shifts
- Cost becomes prohibitive
## References
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [Benchmark Results](link-to-internal-benchmarks)
- [Cost Analysis Spreadsheet](link-to-analysis)
ADR Statuses
Proposed
- Decision is under discussion
- Not yet implemented
- Open for feedback
Accepted
- Decision has been approved
- Implementation in progress or complete
- Current recommendation
Deprecated
- Decision is no longer recommended
- Still in use but should be phased out
- Usually replaced by a newer ADR
Superseded
- Decision has been replaced
- Reference the new ADR
- Kept for historical context
Rejected
- Decision was considered but not adopted
- Explains why it was rejected
- Prevents revisiting
Types of ADRs
Technology Selection
# 005. Use React for Frontend Framework
## Context
Need to select frontend framework for new dashboard application.
Requirements:
- Rich interactive UI
- Real-time updates
- Mobile responsive
- Large community support
- Component reusability
## Decision
Selected React 18 with TypeScript.
## Consequences
[...]
Architecture Pattern
# 008. Adopt Microservices Architecture
## Context
Monolithic application becoming difficult to maintain and deploy.
Challenges:
- Long deployment cycles
- Tight coupling
- Difficult to scale independently
- Team coordination overhead
## Decision
Migrate to microservices architecture over 12 months.
## Consequences
[...]
Security Decision
# 012. Implement OAuth 2.0 for Authentication
## Context
Need secure, industry-standard authentication.
Requirements:
- Third-party login support
- Token-based authentication
- Refresh token rotation
- Security best practices
## Decision
Implement OAuth 2.0 with PKCE flow.
## Consequences
[...]
Infrastructure Choice
# 015. Deploy on AWS Using ECS Fargate
## Context
Need container orchestration solution.
Options evaluated:
- Self-managed Kubernetes
- AWS ECS Fargate
- Google Cloud Run
- Heroku
## Decision
Use AWS ECS Fargate for container deployment.
## Consequences
[...]
ADR Best Practices
1. Write When Decision Is Made
- Document as decisions happen
- Don't wait until later
- Capture context while fresh
2. Be Specific and Concrete
- Avoid vague language
- Include concrete examples
- Reference metrics and data
3. Acknowledge Trade-offs
- Every decision has trade-offs
- Be honest about limitations
- Don't oversell the solution
4. Link Related ADRs
- Reference superseded ADRs
- Note related decisions
- Show decision evolution
5. Keep It Concise
- Focus on key points
- Link to detailed analysis
- 1-2 pages maximum
6. Use Consistent Format
- Same structure for all ADRs
- Predictable organization
- Easy to scan
7. Number Sequentially
- 001, 002, 003, etc.
- Never reuse numbers
- Gaps are OK (rejected ADRs)
ADR Workflow
1. Identify Decision Needed
Team realizes: "We need to decide on a caching strategy"
2. Research Options
Options:
- Redis
- Memcached
- In-memory (application)
- CDN caching
3. Draft ADR
Create ADR with:
- Context and requirements
- Options evaluated
- Recommendation
- Trade-offs
4. Review and Discuss
Team reviews:
- Technical lead approval
- Security review if needed
- Architecture team input
5. Accept and Implement
- Mark as "Accepted"
- Publish to Confluence
- Implement the decision
- Link from related docs
6. Maintain Over Time
- Update if context changes
- Deprecate if superseded
- Add learnings and updates
Confluence Organization
ADR Structure in Confluence
Architecture Space
├── ADR Index (list of all ADRs)
├── ADR Template
└── Decision Records/
├── 001-use-postgresql-for-database.md
├── 002-adopt-microservices-architecture.md
├── 003-implement-oauth-authentication.md
├── 004-use-redis-for-caching.md
└── ...
ADR Index Page
# Architecture Decision Records
## Active Decisions
| Number | Title | Date | Status | Decision Makers |
|--------|-------|------|--------|-----------------|
| 015 | Deploy on AWS ECS Fargate | 2024-01-20 | Accepted | DevOps Team |
| 014 | Use GraphQL for API | 2024-01-18 | Accepted | Backend Team |
| 013 | Implement Feature Flags | 2024-01-15 | Accepted | Engineering |
## Deprecated Decisions
| Number | Title | Date | Status | Superseded By |
|--------|-------|------|--------|---------------|
| 007 | Use MongoDB | 2023-06-10 | Deprecated | ADR-001 |
| 003 | Deploy to Heroku | 2023-03-15 | Deprecated | ADR-015 |
## Rejected Proposals
| Number | Title | Date | Reason |
|--------|-------|------|--------|
| 011 | Use Vue.js | 2023-11-20 | Team lacks expertise |
| 006 | Self-host Kubernetes | 2023-05-10 | Too much operational overhead |
## Categories
### Infrastructure
- ADR-001: Database Selection
- ADR-015: Container Orchestration
### Frontend
- ADR-005: Frontend Framework
- ADR-009: State Management
### Backend
- ADR-012: Authentication Method
- ADR-014: API Design
### Security
- ADR-012: OAuth 2.0 Authentication
- ADR-016: Encryption at Rest
Templates for Different Decision Types
Technology Selection Template
# [Number]. Select [Technology Type] for [Purpose]
**Date**: YYYY-MM-DD
**Status**: Proposed
**Decision Makers**: [Team]
## Context
### Requirements
- List functional requirements
- List non-functional requirements
- List constraints
### Evaluation Criteria
1. Criterion 1 (weight: X%)
2. Criterion 2 (weight: Y%)
3. Criterion 3 (weight: Z%)
## Options Evaluated
### Option 1: [Technology A]
**Pros**:
- Pro 1
- Pro 2
**Cons**:
- Con 1
- Con 2
**Score**: X/10
### Option 2: [Technology B]
[Same structure]
### Option 3: [Technology C]
[Same structure]
## Decision
Selected [Technology X] because [brief reasoning].
## Consequences
### Implementation Impact
- What changes are needed
- What stays the same
### Performance Impact
- Expected performance characteristics
- Benchmarks if available
### Cost Impact
- Initial costs
- Ongoing costs
- Hidden costs
### Team Impact
- Training needed
- Learning curve
- Hiring implications
### Risk Assessment
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Risk 1 | High | Medium | Mitigation strategy |
| Risk 2 | Low | High | Mitigation strategy |
Process Change Template
# [Number]. Adopt [Process/Practice]
**Date**: YYYY-MM-DD
**Status**: Proposed
**Decision Makers**: [Team]
## Context
### Current State
- How things work now
- Pain points
- Metrics showing problems
### Desired State
- What we want to achieve
- Success metrics
- Expected benefits
## Decision
Adopt [Process/Practice] with the following approach:
1. Step 1
2. Step 2
3. Step 3
## Consequences
### Team Changes
- New roles or responsibilities
- Required training
- Schedule impacts
### Tooling Changes
- New tools needed
- Integration requirements
- Costs
### Rollout Plan
- Phase 1: Pilot (dates)
- Phase 2: Expansion (dates)
- Phase 3: Full adoption (dates)
### Success Metrics
- Metric 1: Target value
- Metric 2: Target value
- Metric 3: Target value
Updating ADRs
When to Update
DO update when:
- Adding lessons learned
- Noting implementation challenges
- Recording actual vs expected consequences
- Adding references or links
DON'T update when:
- Decision needs to change → Create new ADR
- Context has changed significantly → Create new ADR
- Original reasoning was wrong → Create new ADR with Supersedes
Update Format
Add updates section at the end:
## Updates
### 2024-03-15: Performance Issues Discovered
After 3 months in production, we discovered that [issue]. We've mitigated this by [solution]. Consider ADR-XXX for future improvements.
### 2024-06-20: Cost Higher Than Expected
Actual monthly cost is $X vs expected $Y because [reason]. Updated cost estimates in budget.
How I'll Help
When creating ADRs, I will:
-
Identify the decision:
- What needs to be decided?
- Why is it important?
- Who should be involved?
-
Research context:
- Read related code
- Review existing docs
- Find similar decisions
-
Structure the ADR:
- Use appropriate template
- Fill in all sections
- Add relevant details
-
Evaluate options:
- List alternatives
- Analyze trade-offs
- Provide recommendations
-
Create in Confluence:
- Format as ADF
- Add to ADR index
- Link related documents
-
Maintain over time:
- Add updates
- Track status changes
- Deprecate when superseded
Example Interaction
You: "We just decided to use Redis for caching. Can you create an ADR?"
Me: "I'll create an ADR for the Redis caching decision.
Let me gather some information:
- What were you using before?
- What other options did you consider?
- What were the key factors in choosing Redis?
- Any concerns or trade-offs?
[You provide context]
I'll create ADR-004: Use Redis for Application Caching
Draft:
- Context: Need caching to reduce database load (currently 1000 QPS)
- Evaluated: Redis, Memcached, in-memory caching
- Decision: Redis for persistence, pub/sub, and rich data types
- Consequences: Positive (performance, flexibility), Negative (ops overhead, cost)
Should I create this in Confluence? Which space?"
You: "Yes, space 456789"
Me: [Creates ADR page]
"Created ADR-004 in space 456789!
Link: https://your-domain.atlassian.net/wiki/spaces/456789/pages/...
Also updating the ADR Index to include this new decision."
