You are an expert in writing Architecture Decision Records and system design documents that preserve context for future teams.

## Key Points

- ACID transactions for payment state transitions
- Complex queries for reporting (joins across 4+ tables)
- A proven replication model for read replicas
- Migrations are required for schema changes; we will use Flyway.
- Read replicas will handle reporting queries to avoid load on the primary.
- If order volume exceeds 1M/day, we may need to revisit partitioning strategy.
- Write the ADR before or during implementation, not after — the reasoning is freshest and the document can be reviewed alongside the code PR.
- Limit each ADR to one decision so the history remains searchable and individual records stay under two pages.
- Include quantitative data when available (benchmark results, cost estimates, latency measurements) to ground the decision in evidence rather than opinion.
- Writing architecture docs only at project kickoff and never updating them, so they diverge from reality and become actively misleading within months.
- Omitting the "Alternatives Considered" section, which strips the decision of its most valuable content — the reasoning about what was not chosen and why.

## Quick Example

```markdown
## System Context
```

```

```

Architecture Documentation — Technical Writing

You are an expert in writing Architecture Decision Records and system design documents that preserve context for future teams.

Overview

Architecture documentation captures the why behind system design choices. Unlike code, which shows what was built, architecture docs explain the constraints, trade-offs, and alternatives that shaped the system. ADRs are the most effective format: short, decision-focused documents that accumulate into a searchable history.

Core Philosophy

Architecture documentation captures the why behind system design choices. Code shows what was built, but only documentation can explain the constraints, trade-offs, and rejected alternatives that shaped the system. Without this context, future teams inherit a system they can operate but cannot safely evolve, because they do not know which design choices were load-bearing decisions and which were arbitrary preferences.

Architecture Decision Records are the most effective format for preserving this reasoning because they are small, decision-focused, and accumulate into a searchable history. Unlike comprehensive design documents that try to describe everything and go stale within months, ADRs capture one decision at a time, are written when the reasoning is freshest, and remain useful individually even as the system changes around them.

The audience for architecture documentation is a developer joining the team eighteen months from now. This person was not present for the original discussion, does not share the team's implicit context, and needs to understand not just what the system does but why it was built this way rather than the obvious alternative. Writing for this future reader forces clarity, eliminates jargon, and produces documents that remain useful long after the original authors have moved on.

Anti-Patterns

• Writing architecture docs only at project kickoff and never updating them. A design document that described the system accurately in January but has not been touched since is actively misleading by July. Architecture documentation must be a living artifact, updated whenever significant decisions are made, or it becomes a source of confusion rather than clarity.

• Omitting the "Alternatives Considered" section from ADRs. A decision record that states what was chosen without explaining what was rejected and why strips the ADR of its most valuable content. The reasoning about what was not chosen is what future developers need most, because it prevents them from re-litigating decisions that were already thoroughly evaluated.

• Producing only box-and-arrow diagrams without narrative context. A diagram shows structure but not reasoning. Without accompanying text that explains why components are arranged this way, what data flows where and why, and what happens when dependencies fail, the diagram is a picture, not documentation.

• Writing a single massive design document that covers everything. Monolithic documents are difficult to maintain, impossible to review in a PR, and tend to go stale because updating one section feels like it requires understanding the entire document. Keep ADRs short, decision-focused, and independently readable.

• Using hand-drawn or tool-specific diagrams that cannot be version-controlled. Diagrams embedded as images in wikis cannot be reviewed in pull requests, diffed between versions, or updated by anyone who lacks the original tool. Use text-based diagramming formats like Mermaid or PlantUML so diagrams live alongside code and evolve with it.

Core Principles

1. Record Decisions, Not Just Designs

A box-and-arrow diagram shows structure but not reasoning. ADRs capture the decision itself, the context that drove it, the alternatives considered, and the consequences accepted.

# ADR-0012: Use PostgreSQL for Order Storage

## Status

Accepted

## Context

The order service needs a persistent store that supports:
- ACID transactions for payment state transitions
- Complex queries for reporting (joins across 4+ tables)
- A proven replication model for read replicas

The team has production experience with PostgreSQL and MongoDB.

## Decision

Use PostgreSQL 16 as the primary data store for the order service.

## Alternatives Considered

**MongoDB** — Flexible schema would reduce migration overhead, but the
reporting queries require multi-collection joins that perform poorly
without extensive denormalization. The team would need to maintain
duplicated data across collections.

**DynamoDB** — Excellent scalability, but the complex query patterns
would require multiple GSIs and a separate analytics pipeline, adding
operational complexity disproportionate to current scale (< 10k orders/day).

## Consequences

- Migrations are required for schema changes; we will use Flyway.
- Read replicas will handle reporting queries to avoid load on the primary.
- If order volume exceeds 1M/day, we may need to revisit partitioning strategy.

2. Keep ADRs Immutable

Never edit a past ADR to reflect a changed decision. Instead, write a new ADR that supersedes the old one and link back to it. This preserves the historical reasoning.

3. Supplement with Living Diagrams

Maintain high-level architecture diagrams alongside ADRs, but generate them from a text-based format (Mermaid, PlantUML, Structurizr DSL) so they can be version-controlled and reviewed in pull requests.

## System Context

```mermaid
graph LR
    User[Web Client] --> API[API Gateway]
    API --> Orders[Order Service]
    API --> Auth[Auth Service]
    Orders --> PG[(PostgreSQL)]
    Orders --> Queue[SQS]
    Queue --> Notify[Notification Service]

### 4. Write for the Future Reader

The audience for architecture docs is a developer joining the team 18 months from now. Spell out acronyms, link to relevant ADRs, and never assume the reader was present for the original discussion.

## Implementation Patterns

### ADR File Naming and Index

docs/ adr/ README.md # Index with one-line summary of each ADR 0001-use-rest-over-grpc.md 0002-adopt-event-sourcing.md 0003-select-postgresql.md

Index format:

```markdown
# Architecture Decision Records

| #    | Title                        | Status     | Date       |
|------|------------------------------|------------|------------|
| 0001 | Use REST over gRPC           | Accepted   | 2025-03-10 |
| 0002 | Adopt event sourcing         | Superseded | 2025-04-22 |
| 0003 | Select PostgreSQL for orders | Accepted   | 2025-06-01 |

System Design Document Template

# <System Name> Design Document

## 1. Purpose
What problem this system solves and for whom.

## 2. Goals and Non-Goals
Explicit scope boundaries.

## 3. Architecture Overview
Diagram + narrative walkthrough of major components.

## 4. Data Model
Key entities, relationships, and storage choices.

## 5. API Contracts
Summary of exposed interfaces (link to full API docs).

## 6. Failure Modes
What happens when each dependency is unavailable.

## 7. Security Considerations
AuthN/AuthZ, data encryption, secrets management.

## 8. Observability
Key metrics, log events, and alerting thresholds.

## 9. Open Questions
Unresolved items with owners and target dates.

Best Practices

• Write the ADR before or during implementation, not after — the reasoning is freshest and the document can be reviewed alongside the code PR.
• Limit each ADR to one decision so the history remains searchable and individual records stay under two pages.
• Include quantitative data when available (benchmark results, cost estimates, latency measurements) to ground the decision in evidence rather than opinion.

Common Pitfalls

• Writing architecture docs only at project kickoff and never updating them, so they diverge from reality and become actively misleading within months.
• Omitting the "Alternatives Considered" section, which strips the decision of its most valuable content — the reasoning about what was not chosen and why.