donnemartin/system-design-primer

What it is

An organized, continually updated collection of resources for learning how to design systems at scale, aimed at engineers who want a structured path through a broad and scattered topic and at candidates preparing for system design interviews. It combines conceptual explanations with trade-off discussions and worked examples rather than offering a runnable library.

The main body is an index of system design topics: performance vs scalability, latency vs throughput, the CAP theorem, consistency and availability patterns, DNS, CDNs, load balancers, databases, caching, asynchronism and communication. Each section explains the concept, lists pros and cons and points to further reading. A separate solutions folder walks through common interview problems with discussions, diagrams and code, including Pastebin/Bit.ly, Twitter timeline and search, a web crawler, Mint.com, a social graph, a key-value store, Amazon sales ranking and scaling to millions of users on AWS.

How to use it

There is nothing to install to read the guide. Start from the study guide and pick a path by your interview timeline: short, medium or long. The short path emphasizes breadth and solving some questions; the long path asks for more depth and most questions.

A practical first pass:

1. Read the index of system design topics to get the vocabulary and trade-offs.
2. Review the four-step interview approach: outline use cases and constraints, sketch a high-level design, design core components, then scale the design.
3. Pick one worked problem, for example Design Pastebin.com (or Bit.ly), read the exercise, then attempt your own version before comparing with the sample solution.

The README explicitly says you do not need to know everything in it to prepare; expectations depend on experience, role, company and luck, so adjust the guide accordingly.

For memorization, the repo ships Anki decks for system design, system design exercises and object-oriented design exercises, along with Anki. The decks can be imported into Anki and reviewed with spaced repetition. The README also points to a sister repository of interactive coding challenges for coding-interview practice.

Constraints and caveats

The material is educational and largely explanatory; it is not a framework or service you integrate. Several sections are marked incomplete: the object-oriented design section is under development, and the security section notes it could use updates. Some solutions are illustrative rather than production-grade; a 2023 HN commenter who works on crawlers argued that the web crawler back-of-the-envelope estimate overstates average page size by about two orders of magnitude and that the proposed crawl frontier would not hold at the scales described (comment).

The guide's relevance also depends on context: another long-running critique is that most projects never need Netflix-scale architecture and that guides encouraging large-scale design can lead teams toward costly, over-complicated systems (discussion). Treat the content as interview and learning material, and judge when scale is actually warranted.

License and contributions

The code and resources are released under CC BY 4.0 by the author on behalf of himself rather than his employer. Translations are coordinated through Issues, and the repo accepts pull requests for fixes, new sections and translations.

HotRepo's take

This is a long-lived reference rather than a fast-moving project. HotRepo recorded daily gains of roughly 138 to 304 stars across early August 2026 snapshots and about 185–192 stars per day in the Python daily list on 7–8 November 2026, where it reached position 11 on that language list. There is no best all-language daily rank on record, so the chart does not establish an all-language standing. The 2018 HN thread drew 1,273 points and 185 comments, and later 2021 and 2023 threads drew 170 and 112 points, which matches the repo's role as a durable reference people return to. Those discussions also carry a useful counterpoint: practitioners question whether the designed-for-scale assumptions fit typical projects, which is worth keeping in mind when using the interview material.