| name | acc-adr-template |
| description | Generates Architecture Decision Records (ADR) for PHP projects. Creates structured decision documentation with context, decision, and consequences. |
ADR Template Generator
Generate Architecture Decision Records following the standard format.
ADR Format
# ADR-{number}: {Title}
**Status:** {Proposed | Accepted | Deprecated | Superseded}
**Date:** {YYYY-MM-DD}
**Deciders:** {names or roles}
## Context
{What is the issue that we're seeing that motivates this decision?}
## Decision
{What is the change that we're proposing/doing?}
## Consequences
### Positive
{What becomes easier?}
### Negative
{What becomes harder?}
### Risks
{What could go wrong?}
## Alternatives Considered
{What other options were evaluated?}
## References
{Links to relevant resources}
Section Guidelines
Title
# ADR-001: Use Domain-Driven Design Architecture
Format: "ADR-{NNN}: {Verb} {Noun/Concept}"
Good:
- Use Domain-Driven Design
- Implement CQRS Pattern
- Adopt PostgreSQL for Primary Storage
- Separate Read and Write Models
Bad:
- DDD (too short)
- Architecture Decision (too vague)
- We should use DDD (conversational)
Status Values
**Proposed** — Under discussion, not yet decided
**Accepted** — Decided and implemented
**Deprecated** — No longer recommended
**Superseded by ADR-XXX** — Replaced by newer decision
Context Section
## Context
Describe the situation that led to this decision:
- What problem are we solving?
- What forces are at play?
- What constraints exist?
- What is the current state?
Example:
---
The system has grown to 50+ controllers with business logic scattered
across controllers, services, and repositories. This leads to:
- Code duplication across features
- Difficulty testing business rules
- Unclear ownership of business logic
- Tight coupling to Symfony framework
We need a clear structure to organize business logic.
Decision Section
## Decision
State the decision clearly:
- Use active voice
- Be specific about what changes
- Include key implementation details
Example:
---
We will adopt Domain-Driven Design (DDD) with the following structure:
1. **Domain Layer** — Contains entities, value objects, domain events,
and repository interfaces. No framework dependencies.
2. **Application Layer** — Contains use cases that orchestrate domain
objects. Defines DTOs for input/output.
3. **Infrastructure Layer** — Implements repository interfaces,
integrates with database, cache, and external services.
4. **Presentation Layer** — Handles HTTP requests/responses using
ADR pattern (Action-Domain-Responder).
Consequences Section
## Consequences
### Positive
List benefits gained:
- Clearer separation of concerns
- Domain logic independent of framework
- Easier to test business rules
- Better code organization
### Negative
List drawbacks accepted:
- More files and directories
- Learning curve for team
- Initial refactoring effort
- More boilerplate code
### Risks
List potential issues:
- Team may over-engineer simple features
- Boundaries may be drawn incorrectly initially
- Refactoring existing code may introduce bugs
Alternatives Section
## Alternatives Considered
### Alternative 1: {Name}
**Description:** {What is it?}
**Pros:**
- {benefit 1}
- {benefit 2}
**Cons:**
- {drawback 1}
- {drawback 2}
**Why Rejected:** {reason}
### Alternative 2: {Name}
...
Complete Example
# ADR-003: Use PostgreSQL for Primary Database
**Status:** Accepted
**Date:** 2025-01-15
**Deciders:** Tech Lead, Backend Team
## Context
We need to select a primary database for the new order management system.
Requirements include:
- Support for complex queries on order data
- JSONB storage for flexible product attributes
- Strong ACID compliance for financial transactions
- Good performance at 10K orders/day scale
- Team familiarity and ecosystem support
Current tech stack uses MySQL 5.7 for legacy systems.
## Decision
We will use PostgreSQL 16 as the primary database for the following reasons:
1. **JSONB Support** — Native JSON storage with indexing for product
attributes that vary by category
2. **Advanced Types** — UUID, arrays, enums as native types reduce
application-level validation
3. **Better Query Optimizer** — Handles complex JOINs across order,
item, and inventory tables more efficiently
4. **Extensibility** — PostGIS for future location features,
full-text search without external service
Implementation notes:
- Use Doctrine ORM with PostgreSQL-specific types
- Enable UUID generation at database level
- Configure connection pooling with PgBouncer
## Consequences
### Positive
- Native JSONB eliminates need for EAV pattern
- Better query performance for complex reports
- Strong typing catches data issues early
- Modern features reduce application complexity
### Negative
- Team needs PostgreSQL training (2-3 days)
- Different SQL dialect from MySQL
- Hosting costs slightly higher
- No existing internal DBA expertise
### Risks
Migration from MySQL may surface data issues
Performance tuning requires new expertise
Backup/recovery procedures need updating
Upgrade existing MySQL infrastructure
Team familiarity
Existing tooling and procedures
Lower migration effort
JSON support less mature than PostgreSQL
Missing advanced types
Query optimizer less capable
Long-term technical debt outweighs short-term convenience
Document database for flexibility
Schema flexibility
Native JSON
Horizontal scaling
No ACID for multi-document transactions
Team has no experience
Complex queries harder
Financial data requires strong ACID guarantees
[]()
[]()
Internal RFC: Database Selection Criteria
File Naming Convention
docs/adr/
├── 000-adr-template.md # Template file
├── 001-use-ddd.md # First decision
├── 002-implement-cqrs.md # Second decision
├── 003-use-postgresql.md # Third decision
└── README.md # Index of all ADRs
ADR Index Template
# Architecture Decision Records
## Active Decisions
| ADR | Date | Title | Status |
|-----|------|-------|--------|
| [001](001-use-ddd.md) | 2025-01-10 | Use Domain-Driven Design | Accepted |
| [002](002-implement-cqrs.md) | 2025-01-12 | Implement CQRS Pattern | Accepted |
| [003](003-use-postgresql.md) | 2025-01-15 | Use PostgreSQL | Accepted |
## Deprecated Decisions
| ADR | Date | Title | Superseded By |
|-----|------|-------|---------------|
| [000](000-monolith.md) | 2024-06-01 | Monolith Architecture | ADR-010 |
Generation Instructions
When generating an ADR:
- Determine next ADR number from existing files
- Clarify the decision being made
- Document context thoroughly
- State decision clearly with specifics
- List consequences (positive, negative, risks)
- Include alternatives that were considered
- Add references to relevant resources
- Update ADR index file
