---
name: architecture-decisions
description: Document and track architecture decisions with ADRs (Architecture Decision Records). Know why decisions were made.
---

# Architecture Decision Records

Every significant decision MUST be documented. Future you will thank present you.

## What is an ADR?

A short document explaining:
- WHAT was decided
- WHY it was decided
- WHAT alternatives were considered
- WHAT are the consequences

## When to Write ADR

Write an ADR when:
- Choosing a technology/framework
- Designing system architecture
- Making security decisions
- Changing database schema significantly
- Choosing between approaches
- Any decision that's hard to reverse

## ADR Template

```markdown
# ADR-[NUMBER]: [TITLE]

**Date:** [YYYY-MM-DD]
**Status:** [Proposed | Accepted | Deprecated | Superseded by ADR-X]
**Deciders:** [Raja Terakhir / Team]

## Context

[What is the issue that we're seeing that is motivating this decision?]

## Decision

[What is the change that we're proposing and/or doing?]

## Alternatives Considered

### Option 1: [Name]
- Pros: ...
- Cons: ...

### Option 2: [Name]
- Pros: ...
- Cons: ...

## Consequences

### Positive
- [Good outcome 1]
- [Good outcome 2]

### Negative
- [Trade-off 1]
- [Trade-off 2]

### Risks
- [Risk 1 and mitigation]

## Related

- Related to: [ADR-X]
- Supersedes: [ADR-Y]
```

## Example ADR

```markdown
# ADR-001: Use Unix Sockets Instead of TCP Ports

**Date:** 2026-01-29
**Status:** Accepted
**Deciders:** Raja Terakhir

## Context

We need to expose backend services to Nginx for reverse proxying.
Traditional approach uses TCP ports (e.g., localhost:8080).

## Decision

Use Unix Domain Sockets for all internal service communication.

Architecture:
```
Cloudflare Tunnel → Nginx → Unix Socket → Service
```

## Alternatives Considered

### Option 1: TCP Ports
- Pros: Familiar, easy to debug with curl
- Cons: Port conflicts, network attack surface, slower

### Option 2: Unix Sockets ✅ (Chosen)
- Pros: No network exposure, file permissions, faster
- Cons: Slightly harder to debug, local only

## Consequences

### Positive
- Zero network attack surface for internal services
- No port conflict management needed
- 10-30% faster than TCP loopback
- File system permissions for access control

### Negative
- Can't curl directly to service (need --unix-socket)
- Only works on same machine

### Risks
- Socket file permissions must be managed
  - Mitigation: Set proper permissions in docker-compose

## Related

- Implements: Security Policy S-001
```

## ADR Numbering

```
ADR-001 through ADR-999

Categories (optional prefix):
- ARCH-001: Architecture decisions
- SEC-001: Security decisions
- DATA-001: Data/database decisions
- API-001: API design decisions
- INFRA-001: Infrastructure decisions
```

## ADR Storage

```
project/
├── docs/
│   └── adr/
│       ├── README.md (index)
│       ├── ADR-001-unix-sockets.md
│       ├── ADR-002-jwt-authentication.md
│       └── ADR-003-postgresql-over-mysql.md
```

## ADR Index Template

```markdown
# Architecture Decision Records

| ID | Title | Status | Date |
|----|-------|--------|------|
| [ADR-001](ADR-001-unix-sockets.md) | Use Unix Sockets | Accepted | 2026-01-29 |
| [ADR-002](ADR-002-jwt-auth.md) | JWT Authentication | Accepted | 2026-01-29 |
| [ADR-003](ADR-003-postgresql.md) | PostgreSQL over MySQL | Accepted | 2026-01-29 |
```

## Auto-Generate ADR

When making significant decisions, Claude should:

1. Recognize decision moment
2. Generate ADR automatically
3. Save to docs/adr/
4. Update index
5. Reference in commit message

```
Commit: "feat: implement JWT auth (see ADR-002)"
```

## Decision Log Integration

For quick decisions that don't need full ADR:

```markdown
## Decision Log

| Date | Decision | Reason | By |
|------|----------|--------|-----|
| 2026-01-29 | Use Fiber over Gin | Better performance, cleaner API | Raja Terakhir |
| 2026-01-29 | Redis for sessions | Fast, built-in TTL | Raja Terakhir |
```

## Review Triggers

Revisit ADRs when:
- Technology becomes deprecated
- Better alternatives emerge
- Original constraints change
- Problems appear from decision
- Team grows significantly