# ADR-{NUMBER}: {TITLE}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-xxx}

## Date
{YYYY-MM-DD}

## Context
What is the issue that we're seeing that motivates this decision?
What are the forces at play (technical, political, social)?

## Decision
What is the change we're proposing and/or doing?

## Rationale
Why is this change being made?
What alternatives were considered?
Why was this option chosen over alternatives?

## Consequences

### Positive
- Benefit 1
- Benefit 2

### Negative
- Drawback 1
- Drawback 2

### Neutral
- Side effect 1

## Alternatives Considered

### Option A: {Name}
**Pros:**
- Pro 1
- Pro 2

**Cons:**
- Con 1
- Con 2

**Why not chosen:** Reason

### Option B: {Name}
...

## References
- [Link to relevant doc]
- [Link to RFC/proposal]

# ADR-001: Use PostgreSQL for Primary Database

## Status
Accepted

## Date
2024-01-15

## Context
We need to select a primary database for the new user management service.
The service will handle 10K concurrent users with complex querying needs.
Team has experience with both PostgreSQL and MongoDB.

## Decision
Use PostgreSQL 15 as the primary database.

## Rationale
- Strong ACID compliance needed for user data integrity
- Complex relational queries required (user → roles → permissions)
- Team has more production experience with PostgreSQL
- Better tooling for schema migrations (Prisma, Drizzle)

## Consequences

### Positive
- Strong consistency guarantees
- Excellent query performance with proper indexing
- Mature ecosystem and tooling

### Negative
- Horizontal scaling more complex than NoSQL
- Schema migrations require careful planning

### Neutral
- Need to set up connection pooling (PgBouncer)

## Alternatives Considered

### MongoDB
**Pros:** Flexible schema, easy horizontal scaling
**Cons:** Eventual consistency, complex transactions
**Why not chosen:** ACID requirements for user data

### MySQL
**Pros:** Similar features, team familiarity
**Cons:** Less advanced features (JSON, arrays)
**Why not chosen:** PostgreSQL's superior feature set

## References
- [PostgreSQL 15 Release Notes](https://postgresql.org)
- [Team RFC: Database Selection](internal-link)

docs/
└── architecture/
    └── decisions/
        ├── README.md           # Index of all ADRs
        ├── 0001-use-postgresql.md
        ├── 0002-adopt-graphql.md
        ├── 0003-microservices-boundary.md
        └── template.md         # ADR template

Proposed → Under Review → Accepted
                              ↓
                         In Effect
                              ↓
              ┌───────────────┴───────────────┐
              ↓                               ↓
         Deprecated                    Superseded by new ADR