# Architecture Decision Record (ADR) Generator Skill Generate Architecture Decision Records to document important architectural decisions. ## ADR Template ```markdown # ADR-{number}: {Title} ## Status {Proposed | Accepted | Deprecated | Superseded by ADR-XXX} ## Context What is the issue that 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 - ... - ... ### Negative - ... - ... ### Neutral - ... ## Alternatives Considered What other options were evaluated? ### Alternative 1: {Name} **Description**: ... **Pros**: - ... **Cons**: - ... **Why not chosen**: ... ### Alternative 2: {Name} **Description**: ... **Pros**: - ... **Cons**: - ... **Why not chosen**: ... ## Implementation Notes Any specific implementation details or considerations. ## References - Link to relevant documentation - Link to related ADRs - Link to discussions ``` ## Common ADR Topics ### 1. Technology Selection - Programming languages - Frameworks and libraries - Databases - Cloud providers - Message queues - Caching solutions ### 2. Architecture Patterns - Microservices vs Monolith - Event-driven architecture - CQRS and Event Sourcing - API Gateway patterns - Service mesh adoption ### 3. Data Management - Database choice (SQL vs NoSQL) - Data modeling approach - Caching strategy - Data migration strategy - Backup and recovery ### 4. Security - Authentication mechanism - Authorization approach - Encryption standards - Secret management - API security ### 5. Development Practices - Branching strategy - Code review process - Testing strategy - CI/CD pipeline - Deployment strategy ### 6. Infrastructure - Hosting platform - Containerization strategy - Orchestration platform - Monitoring and logging - Disaster recovery ## Example ADR ```markdown # ADR-001: Use PostgreSQL for Primary Database ## Status Accepted ## Context We need to select a database for our new e-commerce platform. The system needs to: - Handle complex relational data (users, orders, products, inventory) - Support ACID transactions for financial data - Scale to millions of records - Provide good query performance - Support full-text search - Be well-supported and documented ## Decision We will use PostgreSQL 16 as our primary database. ## Consequences ### Positive - **ACID compliance**: Ensures data consistency for financial transactions - **Rich data types**: JSON, arrays, and custom types provide flexibility - **Full-text search**: Built-in FTS capabilities reduce dependency on external search engines - **Mature ecosystem**: Excellent tooling, extensions, and community support - **Strong consistency**: Suitable for financial and inventory data - **Performance**: Query planner and indexing options provide good performance - **Cost-effective**: Open-source with no licensing fees - **Extensions**: PostGIS for location, pg_cron for scheduling, etc. ### Negative - **Vertical scaling**: Harder to scale horizontally compared to NoSQL - **Operational complexity**: Requires expertise for tuning and maintenance - **Read replicas**: Additional setup for read-heavy scaling - **Storage**: Can be more storage-intensive than some alternatives ### Neutral - **Learning curve**: Team has SQL experience, so moderate learning curve - **Hosting**: Available on all major cloud providers ## Alternatives Considered ### Alternative 1: MySQL **Description**: Popular open-source relational database **Pros**: - Widely used and supported - Good performance for read-heavy workloads - Large ecosystem **Cons**: - Less advanced features than PostgreSQL - JSON support not as robust - Less powerful full-text search - Some storage engines lack ACID compliance **Why not chosen**: PostgreSQL offers more advanced features that align better with our requirements (JSON, full-text search, complex queries). ### Alternative 2: MongoDB **Description**: Document-oriented NoSQL database **Pros**: - Flexible schema - Horizontal scaling - Fast writes - Good for rapidly changing data models **Cons**: - Eventually consistent (can be configured for strong consistency with performance impact) - Less suitable for complex relational queries - Transactions across collections more complex - Not ideal for financial data **Why not chosen**: Our data is highly relational and requires strong ACID guarantees for financial transactions. ### Alternative 3: Amazon DynamoDB **Description**: Fully managed NoSQL database service **Pros**: - Fully managed, no ops overhead - Excellent scalability - Low latency - Pay per usage **Cons**: - Vendor lock-in - Limited query capabilities - More expensive at scale - Requires different data modeling approach **Why not chosen**: Relational model better fits our use case, and we want to avoid vendor lock-in. ## Implementation Notes 1. **Version**: Use PostgreSQL 16 for latest features 2. **Hosting**: Deploy on AWS RDS for managed service benefits 3. **Extensions**: Enable pg_trgm for fuzzy search, pg_stat_statements for monitoring 4. **Connection Pooling**: Use PgBouncer for connection management 5. **Backup**: Daily automated backups with point-in-time recovery 6. **Monitoring**: CloudWatch metrics + custom dashboard 7. **Read Replicas**: Configure 2 read replicas for read-heavy queries 8. **Migration**: Use TypeORM migrations for schema changes ## References - [PostgreSQL Documentation](https://www.postgresql.org/docs/) - [AWS RDS PostgreSQL](https://aws.amazon.com/rds/postgresql/) - [Database Comparison Spike](https://company.com/docs/db-comparison) - [Team Discussion Thread](https://company.slack.com/archives/C123/p456) ``` ## Best Practices ### 1. Number ADRs Sequentially Use ADR-001, ADR-002, etc. Never reuse numbers. ### 2. Keep ADRs Immutable Once accepted, don't modify. Create new ADR to supersede if needed. ### 3. Be Specific Include concrete technical details, not vague statements. ### 4. Document Trade-offs Every decision has pros and cons. Document both honestly. ### 5. Link Related ADRs Reference related decisions to show evolution. ### 6. Update Status Mark as Deprecated or Superseded when decision changes. ### 7. Include Team Input Document that stakeholders were consulted. ### 8. Write for Future Readers Someone reading 2 years later should understand why the decision was made. ### 9. Keep It Concise Aim for 1-2 pages. Link to detailed analysis separately. ### 10. Review Periodically Revisit ADRs annually to ensure they're still relevant. ## ADR Lifecycle 1. **Proposed**: Initial draft, under discussion 2. **Accepted**: Team has agreed, implementation can proceed 3. **Implemented**: Decision has been executed 4. **Deprecated**: No longer recommended but not formally replaced 5. **Superseded**: Replaced by a newer ADR ## Storage Store ADRs in version control: ``` docs/ architecture/ decisions/ 001-use-postgresql.md 002-adopt-microservices.md 003-use-react-native.md README.md (index of all ADRs) ``` ## Index Template ```markdown # Architecture Decision Records ## Active - [ADR-001: Use PostgreSQL for Primary Database](001-use-postgresql.md) - [ADR-002: Adopt Microservices Architecture](002-adopt-microservices.md) ## Superseded - [ADR-003: Use Redux for State Management](003-use-redux.md) - Superseded by ADR-010 ## Deprecated - None ``` ## Lightweight Alternative For smaller decisions, use a simplified format: ```markdown # Decision: {Title} ## Context Brief context (2-3 sentences) ## Decision What we're doing (2-3 sentences) ## Trade-offs - **Pro**: ... - **Pro**: ... - **Con**: ... - **Con**: ... ``` ## Review Checklist Before accepting an ADR: - [ ] Context clearly explains the problem - [ ] Decision is specific and actionable - [ ] Consequences (positive and negative) are documented - [ ] At least 2 alternatives were considered - [ ] Trade-offs are honestly assessed - [ ] Implementation notes provide enough detail - [ ] References are included - [ ] Stakeholders have reviewed - [ ] ADR number is assigned - [ ] Status is set correctly