System Design Primer

What it is

System Design Primer is an organized collection of resources for learning how to design large-scale systems and for preparing for the system design interview. Its owner, Donne Martin, writes that a vast number of resources on system design principles are scattered throughout the web, and this repository gathers them. It is a long README with folders beside it, not a program. The README holds summaries of system design topics with their pros and cons, and says everything is a trade-off. Each section links to deeper reading. Beside it sit solutions to practice questions and three Anki flashcard decks.

1. Pick your timeline in the study guide
2. Read the topic summaries, from DNS to security
3. Learn the four steps for an interview question
4. Try a practice question before you open its solution
5. Review the ideas with the Anki decks

Who it suits

People preparing for a system design interview, and engineers who want a map of how large systems fit together. The README says system design is a required part of the technical interview process at many tech companies. It also says you do not need to know everything in it, and that you should start broad and go deeper in a few areas. More experienced candidates are generally expected to know more.

Skip it if you want a finished, linear course. The README says some topics are still under development, and it marks the object oriented design solutions the same way.

Where to use it

Anywhere you can open a web page or a Markdown file, and in Anki for the flashcards.

• GitHub: the README, with an index that links to each section
• A local copy: a ZIP download or a clone, opened in any Markdown viewer
• Anki: the three flashcard decks, which the README calls great for use while on-the-go. Anki’s site says the computer version and AnkiDroid for Android are free, and that AnkiMobile is the official iOS app, whose purchases help fund Anki’s development
• A notebook tool: for the six object oriented design notebooks
• Translations: the README links Japanese, Simplified Chinese and Traditional Chinese versions

The README gives no steps for any coding agent. Mindket’s notes for Claude Code, Codex and Cursor are ordinary steps for giving an agent the files to read, and they say so.

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder. The primer itself needs no install, and the README gives no install line.

1. Read the README on the repository page. It is under the file list, in your browser.
2. Keep a copy with Download ZIP or a clone. Download ZIP is GitHub’s own, on the Code button. The first block below clones the repository.
3. Import a flashcard deck into Anki. Install Anki, save a deck file, then choose File, Import in Anki and pick the file.
4. Send a change as CONTRIBUTING.md says. That means fork, clone your fork, branch, commit, push and open a pull request.

The first block is the clone address GitHub reports for the repository. The second block is the command set from CONTRIBUTING.md, without its $ prompts. Replace YourLogin with your GitHub name, my-feature with a branch name and modified_files with the files you changed. CONTRIBUTING.md says not to work in the master branch.

git clone https://github.com/donnemartin/system-design-primer.git

git clone git@github.com:YourLogin/system-design-primer.git
cd system-design-primer
git checkout -b my-feature
git add modified_files
git commit
git push -u origin my-feature

The last step happens on GitHub: open your fork’s page and click Pull Request. The clone line in the second block uses an SSH address, which needs an SSH key set up with GitHub (Mindket’s note, ordinary Git).

How to use it

Open the Study guide and pick your timeline: short, medium or long. Then read “System design topics: start here”, which begins with a Harvard scalability lecture and a scalability article. After the topics, work the questions. Write your own answer to each step before you open the solution.

The README’s four steps are to outline use cases, constraints and assumptions, to create a high level design, to design core components and to scale the design. It calls the interview an open-ended conversation that you are expected to lead. An agent can play the interviewer while you lead.

Read "How to approach a system design interview question" in README.md. Then act as the interviewer for "Design a web crawler". Let me lead through the four steps, and do not open solutions/system_design/web_crawler/README.md until I say I am done.

Ask the agent to quote the line it used, so you can compare it with the page. The README links many videos and articles, and an agent cannot watch a video for you.

Example

Take the first question, Design Pastebin.com (or Bit.ly). Write your own scope first. Then open the solution. It scopes the problem to six use cases. A user enters a block of text and gets a randomly generated link. A user enters a paste’s url and views the contents. The user is anonymous. The service tracks analytics of pages, deletes expired pastes and has high availability.

Its stated assumptions include 10 million users, 10 million paste writes per month, 100 million paste reads per month and a 10:1 read to write ratio. It then follows the same four steps, and closes with additional talking points such as NoSQL, caching and security. You compare each of your four answers with its answer.

For newcomers and experts

If you are new. System design is the work of deciding how the parts of a large service fit together, and what happens when traffic grows. You do not need to read all of it. The README says so, and its study guide has a short timeline for exactly that.

Start with the Harvard lecture. It covers vertical scaling, horizontal scaling, caching, load balancing, database replication and database partitioning. The scalability article comes next, linked as a web.archive.org copy, in four parts: clones, databases, caches and asynchronism.

For experts. After the high-level trade-offs of performance vs scalability, latency vs throughput and availability vs consistency, the README goes topic by topic.

• Patterns: consistency (weak, eventual, strong) and availability (fail-over, replication)
• Network: DNS, CDNs, load balancers and reverse proxies
• Services: the application layer, microservices and how services find each other
• Data: relational databases, NoSQL and how to choose between them
• Cache: client, CDN, web server, database and application caching, with cache-aside, write-through, write-behind and refresh-ahead
• Async and communication: message queues, task queues, back pressure, HTTP, TCP, UDP, RPC and REST
• Security

The Appendix adds a powers of two table, latency numbers every programmer should know, and more interview questions with outside links. It also has tables of real world architectures and company architectures, and a list of company engineering blogs. The README’s Under development list names three topics: distributed computing with MapReduce, consistent hashing and scatter gather.

Good to know

Reading the primer runs nothing on your computer. The questions are about what it links to and what you open.

• License: CC BY 4.0. LICENSE.txt reads “Copyright 2017 Donne Martin” and “Creative Commons Attribution 4.0 International License (CC BY 4.0)”. GitHub’s own license field reads “Other”. Every article, talk and paper the README links to has its own owner and terms
• Links: the README points to many outside articles, videos and slide decks, some as web.archive.org copies, and many are plain http links. One can be dead on the day you click it
• Flashcards: the decks are Anki package files. Anki’s manual says a package can carry the author’s scheduling information, and Anki 23.10 and later lets you leave “Import any learning progress” unselected to remove it. Mindket’s notes did not open the decks
• Notebooks: the LRU cache notebook starts a code cell with %%writefile lru_cache.py, and its saved output reads “Overwriting lru_cache.py”. The folder already holds the repository’s own lru_cache.py, so running that cell overwrites it
• Pictures: the Pastebin and AWS scaling solutions, the two Mindket’s notes read, load pictures from i.imgur.com over plain http
• Outbound: reading loads GitHub and whatever site a link opens. Git and Anki are your own programs, and AnkiWeb’s sync is a separate service that these notes do not turn on
• Removal: delete the local folder. A fork stays in your GitHub account until you delete it in the fork’s settings (Mindket’s note, ordinary GitHub). Remove a deck inside Anki