System Architecture
Critical rules
- No universals — only trade-offs in context. Prefer the simplest design that meets current needs and enables growth.
- Always present 2–3 valid approaches; analyze gains and losses explicitly.
- Record expensive-to-reverse decisions as ADRs; never delete historical ADRs.
- Earn complexity (microservices, sharding) when boundaries and scale demand it — not because a famous company did.
- Before choosing patterns or writing ADRs, read references/patterns.md and references/adr-template.md.
Workflow
- Understand context: business needs, team skills, time/budget constraints.
- Identify 2–3 approaches; fill a trade-off table (see references/patterns.md).
- Check what is hard to change later and what matches team capabilities.
- Decide and document with the ADR template in references/adr-template.md.
- Define boundaries/contracts so teams can move independently.
- Revisit when team size, scale, or bounded contexts materially change.
Resources
- references/patterns.md — monolith→serverless, DB choice, scale, CAP, rationalizations. Read when evaluating options.
- references/adr-template.md — ADR format, example, lifecycle. Read when recording a decision.
Validation
- [ ] Context understood before recommending
- [ ] Multiple approaches identified with explicit trade-offs
- [ ] Long-term change cost considered
- [ ] ADR written for significant decisions
- [ ] Matches team capabilities; simplest workable solution
Constraints
- Do not design for nonexistent problems or write ADRs for trivial reversible choices.
- Related:
documentation-standards,design-principles,api-design,resilience,data-visualization.