# System Architecture

> Documents and evolves system architecture with explicit boundaries, ADRs, and trade-off records. Use this skill when making or recording cross-cutting architectural decisions. Do not use when/for local function design (use design-principles or fn-args-deps) or UI component structure (use react-development).

- Skill: `jagreehal/system-architecture` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jagreehal/system-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/system-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/system-architecture

---


# 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](references/patterns.md) and [references/adr-template.md](references/adr-template.md).

## Workflow

1. Understand context: business needs, team skills, time/budget constraints.
2. Identify 2–3 approaches; fill a trade-off table (see [references/patterns.md](references/patterns.md)).
3. Check what is hard to change later and what matches team capabilities.
4. Decide and document with the ADR template in [references/adr-template.md](references/adr-template.md).
5. Define boundaries/contracts so teams can move independently.
6. Revisit when team size, scale, or bounded contexts materially change.

## Resources

- [references/patterns.md](references/patterns.md) — monolith→serverless, DB choice, scale, CAP, rationalizations. Read when evaluating options.
- [references/adr-template.md](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`.