Home

System Architect — System Design Wiki

The detailed companion to the system-architect agent in harness-kit.

The agent turns a problem into a rigorous System Design Doc, then runs an adversarial design review. It works by picking a topic skill — one per classic system design problem, drawn from the System Design podcast series. This wiki holds the deep version of each: theory, the reference architecture, the trade-offs, and the canonical references. The skill files in the repo are the condensed, agent-facing form; these pages are the human-facing study material.

How the agent works

Agent = Model + Harness (Böckeler/Fowler). The harness here is three layers:

• Guides (feedforward) — the design method steers before the agent writes.
• Sensors (deterministic feedback) — structure and rigor checks gate after writing.
• Evals (inferential feedback) — an LLM judge scores quality and review depth.

Humans stay on the loop: improve the guides, sensors, and evals, not just one output.

Commands: /system-design:design, /system-design:review, /system-design:run.

The method

Read this first. It is the lens every topic page applies.

• System Design Method — the 13-stage method, the three pillars (reliability, scalability, maintainability), back-of-envelope numbers, and the canon (who each idea belongs to).

Topic playbooks (the series)

#	Page	Design problem
1	URL Shortener	TinyURL/bit.ly — read-heavy key lookup, short-code generation, cache, abuse
2	Rate Limiter	distributed throttling, token bucket, fail-open, multi-region budgets
3	Search Engine	web crawler, indexing, ranking, query serving at scale

More episodes land as new pages and new skills/{topic}/ playbooks. Candidates: API gateway, distributed queue, news feed, distributed cache, notification system.

How to use a page

Each topic page follows the same shape so you can compare designs across problems:

1. Problem and why it is deceptive — what looks simple and what actually bites.
2. Requirements and scale — functional, non-functional, back-of-envelope sizing.
3. The design — the reference architecture, deep dives on the risk-carrying parts.
4. Theory — the algorithms and data structures, explained, not just named.
5. Trade-offs — the tensions a staff engineer must explain.
6. Failure and operations — what breaks, how it resists, how you know.
7. References — the books, papers, and talks behind the ideas.

Global references

The backbone for every page.

• Martin Kleppmann, Designing Data-Intensive Applications (O'Reilly, 2017). The single best source.
• Jeff Dean, Designs, Lessons and Advice from Building Large Distributed Systems (LADIS 2009) — the "numbers everyone should know".
• Werner Vogels, Everything fails all the time / Amazon — design for failure.
• Pat Helland, Life Beyond Distributed Transactions (CIDR 2007), Immutability Changes Everything (2015).
• Michael Nygard, Release It! (2nd ed., 2018) — stability patterns.
• John Ousterhout, A Philosophy of Software Design (2018).
• Birgitta Böckeler, Harness engineering for coding agent users, martinfowler.com (2026).