System Design Architecture

Software System Design & Architecture

What this is

A decision layer plus a deep reference library for designing real systems. The body below is the framework; the heavy, link-rich material lives in references/*.md and loads only when you open it (progressive disclosure — cheap until needed). Start every non-trivial design from the frameworks here, then pull the matching reference file.

Navigation: references/INDEX.md is the master map. Ten reference files, three checklists, one worked example. When a bundled reference covers a high-stakes question (security, capacity math, cost, archetype choice), consult it rather than answering from memory — the links are the authority.

When to use

Designing or reviewing a backend/SaaS · scaling low→high volume · security hardening · capacity/threshold analysis · cost projection · choosing an architecture style · listing what components a product needs · picking API/ network standards · choosing cloud services. If the task is "design/scale/secure/ cost/choose-architecture for a software system," this skill applies.

The design method (use in order)

1. Frame & quantify. Requirements + numbers: users, RPS (avg and peak), data/day, read:write ratio, latency SLO (p50/p99), availability target, constraints (team, budget, compliance). No numbers → no design. → checklists/design-review.md §0.
2. Pick the archetype. Match product shape to a style; don't cargo-cult. → references/06-architecture-archetypes.md.
3. Place it on the scaling ladder. Where are you now; what's the next rung and its trigger. Don't build for scale you don't have. → references/03-scaling-ladder.md.
4. Lay out the layers. Enumerate every part the system needs and its choices. → references/07-product-layers.md.
5. Size it. Back-of-envelope capacity, bottleneck, limits/thresholds. → references/04-capacity-limits.md.
6. Secure it. Threat model + the security gate. Not a bolt-on. → references/02-security.md, checklists/security-review.md.
7. Cost it. Unit economics (cost per request/tenant), drivers, elasticity. → references/05-cost-modeling.md.
8. Conform to standards & choose services. API/network standards; managed services per capability. → references/10-open-standards.md, references/08-cloud-providers.md.
9. Review & precedent. Walk the pillars; for each high-scale component, name 3–5 real systems that solved it and cite one. → checklists/design-review.md, references/09-case-studies.md.
10. Record the decisions. Capture each significant, hard-to-reverse choice as an ADR; for contested tech choices use the option-space framework. → references/11-decision-records.md.

examples/worked-design-doc.md shows the method applied to one system.

Core heuristics (the compressed wisdom)

• Quantify or don't design. Peak, not average, sizes the system; tail latency (p99/p99.9), not the mean, defines the experience.
• Monolith-first. A modular monolith is the right default; earn microservices with a real scaling or team-autonomy trigger. Premature distribution is the most common self-inflicted wound.
• Stateless services, state at the edges. Push state into datastores/caches so the app tier scales horizontally.
• Climb the ladder on symptoms, not vibes. Each rung (cache → replica → shard → queue → decompose → multi-region) is a response to a measured bottleneck and buys capacity at the price of complexity/consistency.
• Async to smooth load. A durable log/queue between producer and consumer absorbs spikes, decouples failure, and enables replay.
• Design for failure. Timeouts on every call; retries with backoff + jitter; circuit breakers; bulkheads; idempotency; graceful degradation and load shedding over hard failure.
• Security and cost are requirements, not phases. Threat-model early; state unit economics in the design.
• Conform to open standards (OpenAPI/AsyncAPI/OAuth/OTel) by default; deviation is a documented decision.
• Reason from precedent. Someone at scale has solved your component — name 3–5 real systems and cite how (references/09, awesome-scalability, Builders' Library).
• Cite or die. Every non-obvious claim cites a real source (primary doc/RFC/ paper, named engineering post, or file:line); an uncited or invented-source claim is dropped or demoted to an assumption/open question, never shipped as fact. Record hard-to-reverse choices as ADRs (references/11).

Reference library (load on demand)

Checklists: design-review · production-readiness · security-review.

Related skills

• github-search — the discovery playbook used to build and refresh this corpus.
• everjust-platform — platform-specific invariants when designing for everjust.app.