fatby/architecture-decision-records

--- name: architecture-decision-records description: Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes. --- # Architecture Decision Records Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions. ## When to Use This Skill - Making significant architectural decisions - Documenting technology choices - Recording design trade-offs - Onboarding new team members - Reviewing historical decisions - Establishing decision-making processes ## Core Concepts ### 1. What is an ADR? An Architecture Decision Record captures: - Context: Why we needed to make a decision - Decision: What we decided - Consequences: What happens as a result ### 2. When to Write an ADR | Write ADR | Skip ADR | | -------------------------- | ---------------------- | | New framework adoption | Minor version upgrades | | Database technology choice | Bug fixes | | API design patterns | Implementation details | | Security architecture | Routine maintenance | | Integration patterns | Configuration changes | ### 3. ADR Lifecycle Proposed → Accepted → Deprecated → Superseded ↓ Rejected ## Templates ### Template 1: Standard ADR (MADR Format) markdown # ADR-0001: Use PostgreSQL as Primary Database ## Status Accepted ## Context We need to select a primary database for our new e-commerce platform. The system will handle: - ~10,000 concurrent users - Complex product catalog with hierarchical categories - Transaction processing for orders and payments - Full-text search for products - Geospatial queries for store locator The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID compliance for financial transactions. ## Decision Drivers - **Must have ACID compliance** for payment processing - **Must support complex queries** for reporting - **Should support full-text search** to reduce infrastructure complexity - **Should have good JSON support** for flexible product attributes - **Team familiarity** reduces onboarding time ## Considered Options ### Option 1: PostgreSQL - **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text search, PostGIS for geospatial, team has experience - **Cons**: Slightly more complex replication setup than MySQL ### Option 2: MySQL - **Pros**: Very familiar to team, simple replication, large community - **Cons**: Weaker JSON support, no built-in full-text search (need Elasticsearch), no geospatial without extensions ### Option 3: MongoDB - **Pros**: Flexible schema, native JSON, horizontal scaling - **Cons**: No ACID for multi-document transactions (at decision time), team has limited experience, requires schema design discipline ## Decision We will use **PostgreSQL 15** as our primary database. ## Rationale PostgreSQL provides the best balance of: 1. **ACID compliance** essential for e-commerce transactions 2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce infrastructure complexity 3. **Team familiarity** with SQL databases reduces learning curve 4. **Mature ecosystem** with excellent tooling and community support The slight complexity in replication is outweighed by the reduction in additional services (no separate Elasticsearch needed). ## Consequences ### Positive - Single database handles transactions, search, and geospatial queries - Reduced operational complexity (fewer services to manage) - Strong consistency guarantees for financial data - Team can leverage existing SQL expertise ### Negative - Need to learn PostgreSQL-specific features (JSONB, full-text search syntax) - Vertical scaling limits may require read replicas sooner - Some team members need PostgreSQL-specific training ### Risks - Full-text search may not scale as well as dedicated search engine - JSONB performance may degrade with very large documents - Migration from existing MySQL databases requires careful planning ## Implementation Plan 1. Install PostgreSQL 15 on production servers 2. Configure streaming replication for high availability 3. Create initial schema with product catalog tables 4. Implement connection pooling with PgBouncer 5. Set up monitoring with pg_stat_statements ### Template 2: Lightweight ADR markdown # ADR-0002: Use React for Frontend ## Status Accepted ## Context We need a modern frontend framework for our customer-facing web application. The application requires: - Rich interactive UI with real-time updates - Component-based architecture for reusability - Strong ecosystem and community support - Good TypeScript integration ## Decision Use React 18 with TypeScript. ## Rationale React has the largest ecosystem, best TypeScript support, and the team has prior experience. ## Consequences - Large bundle size may affect initial load time - Need to manage state complexity with additional libraries (Redux/Recoil) ### Template 3: Comprehensive ADR (ISO/IEC 42010 Style) ```markdown # ADR-0003: Microservices Architecture ## Status Accepted ## 1. Introduction ### 1.1 Purpose Document the decision to adopt a microservices architecture for the new payment processing platform. ### 1.2 Scope Applies to all new development for the payment platform. Existing monolithic applications will remain but not receive new features. ### 1.3 Definitions - Microservice: Independently deployable service with single responsibility - Bounded Context: Logical separation of business domains - API Gateway: Entry point for external clients ### 1.4 References - [Domain-Driven Design by Eric Evans] - [Microservices Patterns by Chris Richardson] ## 2. Problem Statement The current monolithic payment application has become: - Difficult to scale specific components - Hard to deploy due to coupling - Resistant to technology evolution - Complex for new developers to understand ## 3. Decision Drivers ### 3.1 Business Drivers - Faster time-to-market for new payment methods - Independent scaling of high-volume components - Gradual migration from legacy systems ### 3.2 Technical Drivers - Polyglot persistence (different databases for different needs) - Independent deployment cycles - Team autonomy and ownership ### 3.3 Constraints - Must maintain 99.99% availability - Must comply with PCI DSS - Team size: 15 developers initially ## 4. Considered Alternatives ### 4.1 Alternative 1: Monolithic Architecture (Status Quo) - Pros: Simpler deployment, easier debugging, no distributed systems complexity - Cons: Scaling limitations, technology lock-in, deployment bottlenecks ### 4.2 Alternative 2: Service-Oriented Architecture (SOA) - Pros: Clear service boundaries, established patterns - Cons: Heavyweight middleware, complex governance, slower evolution ### 4.3 Alternative 3: Microservices Architecture - Pros: Independent scaling, technology flexibility, team autonomy - Cons: Distributed systems complexity, operational overhead, network latency ## 5. Decision Adopt microservices architecture with the following characteristics: - Service Boundaries: Aligned with business capabilities (Payments, Fraud Detection, Settlement, Reporting) - Communication: Synchronous REST APIs for external calls, asynchronous events for internal coordination - Data Management: Database per service, eventual consistency where acceptable - Deployment: Container-based (Docker), orchestrated with Kubernetes - Observability: Centralized logging (ELK), distributed tracing (Jaeger), metrics (Prometheus) ## 6. Rationale The microservices approach best addresses our primary challenges: 1. Scalability: Individual services can scale based on load 2. Team Autonomy: Teams can own services end-to-end 3. Technology Evolution: New payment methods can use modern tech stacks 4. Fault Isolation: Failures in one service don't bring down entire system The increased operational complexity is justified by the business benefits and will be managed through investment in platform engineering. ## 7. Consequences ### 7.1 Positive Impacts - Faster feature development after initial setup - Better resource utilization through targeted scaling - Improved fault tolerance through isolation - Enhanced developer productivity through focused codebases ### 7.2 Negative Impacts - Increased operational overhead (more services to monitor) - Distributed systems complexity (network failures, eventual consistency) - Higher initial development cost (need for API gateways, service discovery) - More complex debugging and tracing ### 7.3 Risks - Risk: Distributed transactions across services Mitigation: Use Saga pattern, accept eventual consistency where possible - Risk: Network latency affecting performance Mitigation: Careful service boundary design, API optimization - Risk: Data consistency issues Mitigation: Clear consistency requirements per use case - Risk: Operational complexity overwhelming teams Mitigation: Invest in platform team, provide self-service tooling ## 8. Compliance & Standards - All services must implement OpenAPI specifications - Service-to-service authentication using JWT - Data encryption in transit (TLS 1.3) and at rest (AES-256) - PCI DSS compliance maintained per service ## 9. Implementation Guidelines ### 9.1 Service Template - Use [organization]/service-template repository - Include Dockerfile, Helm charts, CI/CD pipeline - Implement health checks, metrics endpoints, structured logging ### 9.2 Communication Patterns - External clients → API Gateway → Services - Service-to-service: REST with circuit breakers - Internal events: Message queue (Kafka/RabbitMQ) ### 9.3 Data Management - Each service owns its database - No direct database access between services - Data replication via events where needed ### 9.4 Observability - Structured logging with correlation IDs - Distributed tracing for request flows - Business metrics and alerts ## 10. Success Criteria - 95% of services deploy independently - Mean time to deploy new service < 1 day - P99 latency < 200ms for critical paths - Developer satisfaction score > 4.0/5.0 ## 11. Review Schedule - Initial review: 3 months after first production deployment - Annual review: Assess architecture effectiveness - Trigger review: If developer satisfaction drops below 3.5/5.0 ## Workflow ### 1. Proposing a New ADR 1. Create docs/adr/NNNN-proposed-title.md 2. Use appropriate template 3. Fill in draft content 4. Share with stakeholders for review ### 2. Review Process 1. Technical review by architects 2. Business impact assessment 3. Risk analysis 4. Implementation planning ### 3. Approval & Status Update 1. Update status to "Accepted" or "Rejected" 2. Record approval date and stakeholders 3. Communicate decision to relevant teams ### 4. Maintenance 1. Review ADRs during architecture reviews 2. Update status when decisions change 3. Deprecate when no longer relevant ## Tooling Recommendations ### 1. Documentation Tools - adr-tools: Command-line tool for managing ADRs - log4brains: Static site generator for ADRs - Madr: Markdown Any Decision Records format ### 2. Integration with Development - GitHub Actions: Automate ADR creation - Jira/Linear: Link ADRs to tickets - Slack/Teams: Notify teams of new ADRs ### 3. Visualization - ADR Visualization Tools: Show relationships between decisions - Decision Trees: Map alternatives and choices - Timeline Views: Show decision evolution ## Best Practices ### 1. Writing ADRs - Be concise but complete: Include enough context for future readers - Use plain language: Avoid jargon unless necessary - Include alternatives: Document why other options were rejected - Record consequences: Both positive and negative impacts - Set review dates: Plan for future reassessment ### 2. Managing ADRs - Centralized repository: Keep all ADRs in one place - Consistent numbering: Use sequential numbers (ADR-0001, ADR-0002) - Regular reviews: Schedule periodic architecture reviews - Living documents: Update when circumstances change - Retirement policy: Archive or deprecate when no longer relevant ### 3. Cultural Practices - Transparency: Make ADRs accessible to everyone - Collaboration: Involve multiple stakeholders in decisions - Learning culture: Use past ADRs to inform new decisions - Psychological safety: Allow questioning of past decisions ## Common Pitfalls ### 1. Over-documentation - Problem: ADRs become too long and unreadable - Solution: Use appropriate template for decision complexity ### 2. Under-documentation - Problem: Missing critical context or alternatives - Solution: Use checklist to ensure completeness ### 3. Neglected ADRs - Problem: ADRs written but never reviewed or updated - Solution: Schedule regular architecture reviews ### 4. Decision Avoidance - Problem: Using ADRs to delay decisions - Solution: Set time limits for decision-making ## Examples by Domain ### 1. Infrastructure ADRs - Cloud Provider Selection (AWS vs Azure vs GCP) - Container Orchestration (Kubernetes vs Nomad vs ECS) - Monitoring Stack (Prometheus vs Datadog vs New Relic) ### 2. Application ADRs - Authentication Strategy (OAuth2 vs JWT vs SAML) - API Design (REST vs GraphQL vs gRPC) - State Management (Redux vs MobX vs Context) ### 3. Data ADRs - Database Selection (PostgreSQL vs MySQL vs MongoDB) - Caching Strategy (Redis vs Memcached vs application cache) - Search Solution (Elasticsearch vs Algolia vs built-in) ### 4. Process ADRs - Development Methodology (Agile vs Waterfall vs Hybrid) - Code Review Process (GitHub PRs vs Gerrit vs Phabricator) - Deployment Strategy (Blue-green vs Canary vs Rolling) ## Integration with Other Skills ### 1. Risk Analysis - Use risk assessment frameworks before finalizing decisions - Document risks and mitigation strategies in ADRs ### 2. Project Planning - Link ADRs to project milestones and deliverables - Use ADRs to inform task breakdown and estimation ### 3. Documentation - Generate architecture documentation from ADRs - Create onboarding materials based on key decisions ### 4. Knowledge Management - Use ADRs as part of organizational memory - Search ADRs when facing similar decisions ## Training & Onboarding ### 1. New Team Members - Review key ADRs during onboarding - Understand architectural principles and constraints ### 2. Decision-Making Training - Teach ADR creation and review processes - Develop architectural thinking skills ### 3. Continuous Learning - Regular architecture review meetings - Case studies from past decisions ## Metrics & Improvement ### 1. Quality Metrics - Completeness: Percentage of ADRs with all required sections - Timeliness: Time from decision to documentation - Usage: Frequency of ADR references ### 2. Impact Metrics - Decision quality: Outcomes of documented decisions - Reversal rate: How often decisions are revisited - Stakeholder satisfaction: Feedback on decision process ### 3. Improvement Process - Retrospectives: Review ADR process effectiveness - Benchmarking: Compare with industry best practices - Tooling evaluation: Assess and improve documentation tools ## References 1. MADR: Markdown Any Decision Records 2. Documenting Architecture Decisions 3. ISO/IEC/IEEE 42010: Systems and software engineering — Architecture description 4. Architecture Decision Records in Practice