tomevault-io 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
## Alternatives Considered
### MySQL 8.0
**Description:** Upgrade existing MySQL infrastructure
**Pros:**
- Team familiarity
- Existing tooling and procedures
- Lower migration effort
**Cons:**
- JSON support less mature than PostgreSQL
- Missing advanced types
- Query optimizer less capable
**Why Rejected:** Long-term technical debt outweighs short-term convenience
### MongoDB
**Description:** Document database for flexibility
**Pros:**
- Schema flexibility
- Native JSON
- Horizontal scaling
**Cons:**
- No ACID for multi-document transactions
- Team has no experience
- Complex queries harder
**Why Rejected:** Financial data requires strong ACID guarantees
## References
- [PostgreSQL vs MySQL Comparison](https://example.com/comparison)
- [PostgreSQL 16 Release Notes](https://www.postgresql.org/docs/16/release-16.html)
- 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.