Skill: System Architecture & ADRs

Architecture Decision Record (ADR) Format

An ADR documents why an architectural decision was made, not just what was chosen.

# ADR-NNN: [Decision Title]

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-NNN

## Context
Why are we making this decision? What's the problem?
What constraints do we have (timeline, team size, technical)?
What have we already tried or considered?

## Decision
What exactly are we choosing to do?
Be specific and precise.

## Consequences

### Positive
- Benefit 1
- Benefit 2

### Negative
- Tradeoff 1
- Tradeoff 2

### Mitigations
- How we'll handle negative consequences

Tech Stack Decision Template

Compare 3 options for each major choice:

Decision: Option B
Reasoning: Team knows it, easy to scale, community support

Coupling vs. Cohesion

High Cohesion = related code lives together

• Example: All user auth logic in AuthService module

Low Coupling = modules don't depend on each other heavily

• Example: PaymentService doesn't directly call AuthService; uses events instead

Goal: High cohesion + low coupling = easy to change

Service Granularity Spectrum

When to split from monolith → services:

• Team is >20 engineers (communication overhead)
• Need independent scaling (some services get more traffic)
• Different technology stacks needed (one service needs fast Go, another needs Python ML)
• Deploy frequency conflict (some teams want to deploy hourly, others weekly)

Fitness Functions

Automated architecture compliance checks:

# "Fitness function": verify architecture is maintained

# 1. No circular dependencies
$ grep -r "import.*from.*$module" $module  # Should be empty

# 2. Only public APIs are used across modules
$ grep -r "from.*_internal" # Should be zero

# 3. All HTTP endpoints document schema
$ grep -r "@Post\|@Get" --include="*.ts" | wc -l
$ grep -r "^export.*DTO" --include="*.ts" | wc -l
# These should match (all endpoints have DTOs)

# 4. Database queries use ORM, not raw SQL
$ grep -r "query(.*SELECT" # Should be zero