system-design: one README, five chapters, and no tagged release

The whole course is one README.md, with diagrams/ as the only other asset

Count the root entries and you get .github/, .gitignore, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE, README.md and diagrams/. Everything a reader is meant to learn is inside that one file, and the table of contents at the top of it is a list of anchor links into the same document.

That single-file shape is the first decision to make about the project. There is no site to deploy, no per-chapter file to open, and no navigation outside the file itself, so the ways to consume it are: read it in a browser and use the table of contents, or clone and read it in an editor. What you cannot do is link a reader to one chapter as a standalone document, diff how chapter III changed between two dates, or generate a PDF from a subset without cutting it out yourself.

The diagrams/ folder is the exception that proves the rule. The prose describes what to draw, and the images live beside the file rather than inside it, so an offline reader who clones the repository gets them and someone reading on a phone may have to open them separately.

Twelve headings of networking come before the first database chapter

Chapter I is a networking course, not an architecture course, and the order is deliberate enough to name. It runs IP, OSI Model, TCP and UDP, DNS, Load Balancing, Clustering, Caching, CDN, Proxy, Availability, Scalability and Storage. Chapter II is where databases begin, with Databases and DBMS and SQL databases. A reader who came for load balancers and sharding reads two chapters of protocol fundamentals first.

The IP entry sets the register. IPv4 is described as a 32-bit dot-decimal scheme allowing around four billion addresses, with `102.22.192.181` as the example, and IPv6 as introduced in 1998 with deployment starting in the mid-2000s and still ongoing, using 128-bit hexadecimal notation for about 340e+36 addresses, illustrated with `2001:0db8:85a3:0000:0000:8a2e:0370:7334`. The 340e+36 figure is shorthand notation rather than standard number formatting, so quote it carefully if you reuse it.

The same entry sorts addresses into public, private, static and dynamic, with dynamic described as handed out by a DHCP server and cheaper to deploy because addresses get reused. That is the only count of four in the whole course, and it is about IP addresses.

CAP arrives after the storage engines, followed by PACELC

Chapter II runs fifteen headings in an order that teaches storage before it teaches trade-offs: Databases and DBMS, SQL databases, NoSQL databases, SQL vs NoSQL databases, Database Replication, Indexes, Normalization and Denormalization, ACID and BASE consistency models, CAP theorem, PACELC Theorem, Transactions, Distributed Transactions, Sharding, Consistent Hashing and Database Federation.

The placement is the useful editorial decision. By the time CAP arrives, the reader has already met replication, indexing and normalization, so the theorem lands as a description of a tension between things they have seen rather than as a slogan. PACELC follows immediately as the extension of the same idea to the else branch, which is the only textbook in the file that treats the two theorems as one argument.

Sharding, consistent hashing and database federation close the chapter, so the practical tools arrive after the theory. The cost of the survey approach is that nothing gets depth. Each entry is a few paragraphs that define the term and name the trade-off, which is enough to hold an interview conversation and not enough to size a shard key for your own traffic.

The service layer puts CQRS beside an ESB and a REST, GraphQL, gRPC comparison

Chapter III covers how services talk to each other: N-tier architecture, Message Brokers, Message Queues, Publish-Subscribe, Enterprise Service Bus, Monoliths and Microservices, Event-Driven Architecture, Event Sourcing, CQRS, API Gateway, REST, GraphQL and gRPC, and Long polling, WebSockets and Server-Sent Events.

Three of those headings are patterns the industry has partly moved past, and the course keeps them. Enterprise Service Bus and Publish-Subscribe sit in the same list as Event Sourcing with no editorial on why the first two are less common now, and Monoliths and Microservices is one heading rather than a comparison with a position. That is what a survey does, and it is also what makes the chapter safe to read: it will not steer you into an argument about which style to pick.

Chapter IV is the one place the sequence stops being purely conceptual. Geohashing and Quadtrees, Circuit breaker, Rate Limiting, Service Discovery, SLA, SLO, SLI, Disaster recovery, VMs and Containers, OAuth 2.0 and OIDC, SSO, and SSL, TLS and mTLS. Service discovery and rate limiting sit next to disaster recovery, which is the shortest bridge in the file between theory and the things you actually configure.

The interview material is five product designs in the last chapter

Everything the repository promises about interviews lives in Chapter V, and it is the smallest chapter. It opens with System Design Interviews and then works through URL Shortener, WhatsApp, Twitter, Netflix and Uber. An Appendix closes it with Next Steps and References. That is six headings plus two, against fifteen in the database chapter and thirteen in the service chapter.

So the ratio tells you what this is. A fundamentals course with an interview chapter attached, not a question bank. The five designs are the ones the interviews themselves use, and the course walks them in increasing order of difficulty, from shortening a URL to designing a ride-hailing service.

What the table of contents does not give you is any of the scaffolding an interview candidate needs: no time budget per design, no list of questions to ask, no rubric, no indication of which design to practise when. An appendix named Next Steps is a pointer, not a plan. A reader who wants a mock interview loop has to build that loop themselves.

A star request and a paid ebook share the same file as the CAP theorem

The opening note says the course is also available on the author's own website and as an ebook on leanpub, and asks readers to leave a star as motivation. The same file that explains consistent hashing closes with sponsor-free funding notes and a course link.

That arrangement is worth naming plainly because the repository does not mark which parts are paid. A reader cannot tell from the text whether the Leanpub ebook is the same material in a different format, a condensed version, or an expanded one, and the paid course on the author's site is described in the same sentence as the free repository. If the free text is enough for your purpose, the question does not matter. If you are paying, it is a question the repository does not answer.

The licence sits in the same category. A LICENSE file exists at the root, while the repository metadata reports the licence as unasserted, meaning the automated record could not classify it. For reading and linking that is irrelevant. For copying the text into a company handbook or a course of your own, someone has to open the file and read which licence it is.

One file, no tag, and a last push on 2026-07-08

The project has no GitHub releases, the default branch is main, and the last push was on 2026-07-08. It is not archived.

For a single-file document that matters more than it would for a library. There is no tag to point a reader at, and no changelog, so the only way to tell whether the text you hold is current is to compare commits. If you have mirrored the file into internal documentation, a correction to a single paragraph rewrites the whole document and your mirror has no marker telling you which paragraph moved.

The diagrams/ folder makes this worse in a small way. Images referenced from the text are not versioned with the prose in any way the reader can see, so a diagram that no longer matches its paragraph is not something a diff will point at. Pin the commit you read, and re-fetch rather than trust a copy.

It is a survey, and the References appendix is the handoff to primary sources

Read as a document type, this is a survey with a fixed reading order, and the difference from a reference is that a reference is consulted for one fact while a survey is read once. The IPv4 entry is a short definition of a 32-bit dot-decimal scheme with one example address, and the OSI entry begins by calling the model a logical and conceptual model of network communication. Neither is deep enough to settle a protocol argument, and neither is meant to be.

The Appendix carries a References section, which is the honest handoff. When a course chooses breadth over depth, the references are where the depth lives, and a reader who needs the actual behaviour of a system should go there rather than trusting a paragraph in a career-prep document.

That framing also sets the limit. Nothing in the repository is a template, a checklist or a record format, so a team looking for an architecture decision process will not find one here. It answers what the vocabulary means and roughly when each piece is used, which is a different deliverable from helping you write down a decision you have already made.

Editorial conclusion

system-design suits a candidate who wants one continuous written course to read end to end, and an engineer who wants CAP, PACELC, CQRS and consistent hashing in a single place. It does not suit a team looking for architecture records, decision templates or anything to run against. Verify first which licence the root LICENSE file carries, because the repository metadata reports the licence as unasserted, and read the current revision rather than a mirror, since the last push was on 2026-07-08 and there is no tagged release to diff against.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository