saitarrun 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:
| Factor | Option A | Option B | Option C |
|---|---|---|---|
| Learning curve | Steep | Gentle | Moderate |
| Community | Large | Small | Medium |
| Performance | 1000 rps | 10k rps | 5k rps |
| Scalability | Hard | Easy | Medium |
| Team expertise | None | High | Medium |
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
| Monolith | Distributed Monolith | Microservices |
|---|---|---|
| One codebase, one deploy | One codebase, separate deploys | Many codebases, many deploys |
| Easy to test end-to-end | Harder to test end-to-end | Complex testing, many moving parts |
| Scales vertically (bigger server) | Scales each layer independently | Scales each service independently |
| All-or-nothing deploy risk | Lower deploy risk | Highest deploy risk if not careful |
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