ADR Writing

Purpose

Document significant architecture decisions in a consistent format that captures context, decision rationale, and consequences for future reference.

When to Use

• Technology selection decisions

• Pattern choices

• Major trade-off decisions

• Breaking changes

• Deprecation decisions

Prerequisites

• Decision context understood

• Options evaluated

• Stakeholder input gathered

• Consequences analyzed

Process

Step 1: Determine if ADR Needed

Write ADR when:

• Decision affects structure significantly
• Multiple valid alternatives exist
• Decision is hard to reverse
• Team disagreed on approach
• Decision involves trade-offs

Step 2: Gather Context

Document:

• What prompted the decision
• Business/technical drivers
• Constraints that apply
• Prior decisions affecting this

Step 3: Document Options

For each alternative:

• Description
• Pros and cons
• Why considered
• Why rejected (if not chosen)

Step 4: Write ADR

ADR sections:

• Title and status
• Context
• Decision
• Consequences
• Alternatives considered

Step 5: Review and Store

Process:

• Peer review for accuracy
• Stakeholder review if needed
• Store in docs/architecture/adrs/
• Number sequentially
• Update status as needed

Inputs

Input Type Required Description

decision_context String Yes What's being decided

options JSON Yes Alternatives considered

evaluation Markdown Yes Analysis results

Outputs

Output Type Description

ADR-XXX.md Markdown Decision record

StudyAbroad-Specific Considerations

• Reference GDPR compliance implications

• Note external API dependency impacts

• Consider multi-region implications

Integration Points

• All Agents: Reference ADRs for context

• Documentation Agent: ADR maintenance

Examples

ADR-003: Use PostgreSQL for Primary Database

Status

Accepted

Date

2024-01-10

Context

StudyAbroad-v1 needs a primary database for storing user data, applications, and program information. We need ACID compliance for transactional data, support for complex queries, and good JSON capabilities for flexible program attributes.

Decision

We will use PostgreSQL as our primary database.

Consequences

Positive

• Strong ACID compliance for financial/application data
• Excellent JSON/JSONB support for flexible schemas
• Mature ecosystem with good tooling
• Team has strong PostgreSQL experience
• Good managed options (RDS, Cloud SQL)
• Built-in full-text search for program search

Negative

• Horizontal scaling more complex than NoSQL
• May need to add search engine later for advanced search
• Connection management requires pooling

Risks

• Large table performance may need partitioning
• Read scaling requires replica management

Alternatives Considered

MySQL

• Similar relational capability
• Slightly less JSON support
• Team has less experience
• Rejected: PostgreSQL better fit for JSON needs

MongoDB

• Native JSON document storage
• Easy horizontal scaling
• Less ACID guarantee
• Rejected: Need strong ACID for applications

DynamoDB

• Serverless, auto-scaling
• Limited query flexibility
• Rejected: Query patterns too rigid

Related

• Requires: None
• Enables: ADR-004 (ORM Selection)
• Related: REQ-003 (University search needs)

Validation

• Context clearly explains the need

• Decision is unambiguous

• Consequences are realistic

• Alternatives were genuinely considered

• Format is consistent with other ADRs