# The Engineering Handbook: an open-source HLD and DSA curriculum

> handbook-academy/engineering-handbook hosts two full textbooks, an HLD handbook and a DSA handbook, as Markdown under a CC BY-SA 4.0 license. It is a reading and contribution project, not a library you install.

**handbook-academy/engineering-handbook** — Open-source High-Level System Design and Data Structure & Algorithm handbook. CC BY-SA 4.0, Free Forever.

- Repository: https://github.com/handbook-academy/engineering-handbook
- Website: https://handbook.academy
- Stars: 588 · Forks: 39
- Language: JavaScript
- License: CC-BY-SA-4.0
- Published: 2026-09-20 · Updated: 2026-09-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/handbook-academy-engineering-handbook

## Two handbooks, one repository, one license

The repository holds two separate curricula rather than one book. The HLD Handbook lives in content/hld/ and is described as 159 teaching chapters across 12 parts plus a 22-page Trade-offs Library, 181 pages, roughly 773,000 words, 719 Mermaid diagrams and more than 3,100 citations. The DSA Handbook lives in content/dsa/ and is described as 120 chapters across 15 parts, 37 pattern decision pages, 5 long-form LeetCode editorials and 46 interactive widget specs, with sibling sol.py, sol.java, sol.cpp and sol.go files for 155 problems.

The audience is narrow and specific: engineers preparing for system design or coding interviews, and engineers who want a reference for distributed systems topics that is written as prose rather than as a slide deck. The README states the intent plainly, saying every concept is taught inline as a full-length article rather than as a stub or an external redirect. That is a real editorial commitment. It is also the main reason the repository is large and slow to change.

The umbrella structure is deliberate. The README says additional handbooks, naming operating systems, databases and ML systems as examples, are planned to land alongside HLD and DSA under the same workflow and license. Treat that as a stated plan, not a shipped feature.

## Markdown files plus a quality gate, not a runtime

There is no application to run. The content is Markdown under content/, and the README notes that every .md file renders natively on GitHub, including all 945 Mermaid diagrams, footnotes and cross-references. The websites add search, dark mode, per-chapter diagram zoom, social cards and the interactive DSA widgets on top of the same source files.

The mechanism that keeps the corpus consistent is a set of Node scripts wired into package.json. Each script targets one failure class: markdownlint-cli2 for formatting, typos for spelling, lychee for link checking against lychee.toml, and three custom scripts, check-citations.mjs, check-frontmatter.mjs and check-mermaid.mjs. The last one is the interesting choice. Diagram syntax is validated in CI rather than discovered broken in the browser.

Frontmatter is the other structural mechanism. The README states that every chapter declares date_created and date_updated, which is how a reader can judge how current a page is. That is a better answer to staleness than a single repository-level timestamp, and it is checked automatically rather than left to reviewers.

One consequence worth naming: the CI validates form, not correctness. Nothing in the script list verifies that a claim about TCP, consensus or a LeetCode complexity bound is true. The 3,100+ citations are the project's answer to that, and checking them is a human job.

## Reading it locally and running the content checks

The README points readers at handbook.academy for the landing page, hld.handbook.academy for the HLD curriculum and dsa.handbook.academy for the DSA curriculum, which the README labels as a public beta. Each subdomain serves one book at its root, so HLD chapters sit under hld.handbook.academy/curriculum/... and not under handbook.academy/hld/....

If you want the source, clone the repository and install the dev dependencies. The package.json declares Node 20 or newer and npm 10.8.1 as the package manager, so check your version before installing.

```bash
git clone https://github.com/handbook-academy/engineering-handbook.git
cd engineering-handbook
node --version
npm install
```

The install pulls jsdom, markdownlint-cli2 and mermaid. There is no build output to inspect afterwards; the dependencies exist to check the Markdown.

For a first real use, run the full check suite before you change anything. This gives you a clean baseline, so when a check fails later you know it was your edit and not the checkout.

```bash
npm run check:all
```

That command chains lint, check:typos, check:citations, check:frontmatter, check:mermaid and check:links in that order. Expect it to be the slowest step you run, because check:links reaches the network through lychee.

If you only care about prose, vale is wired separately and can be run on its own:

```bash
npm run prose
npm run stats
```

The stats script reports content statistics, which is the same kind of counting the README uses for its word and diagram figures. To contribute, the README points at CONTRIBUTING.md and STYLE_GUIDE.md; read the style guide before writing a chapter, since the chapter template is enforced by review rather than by a script.

## Where the project stops short

The obvious limitation is that this is a text corpus, and text corpora go stale. The README addresses freshness by claiming continuous updates and per-chapter date_updated fields, but freshness is declared by the author of each chapter. There is no mechanism in the script list that compares a chapter's claims against the current state of the technology it describes.

The DSA Handbook carries a second limitation. Its 46 interactive widget specs live in content/dsa/widgets/ as YAML, and the README describes them as specs rather than as shipped components. The widgets render on dsa.handbook.academy, which the README calls a public beta. If you read the Markdown on GitHub, you get the prose and the diagrams, not the interactive behaviour.

Language coverage in the DSA handbook is uneven by design. The README states that Python is inlined in the chapter while the Java, C++ and Go solutions are linked as sibling files. A Go reader therefore follows an extra hop for every problem, and the in-chapter code they are reading is not in their language.

Finally, the repository is not a substitute for a course with assessment. There are study plans, but nothing tracks what you have completed. If you need graded exercises or a cohort, this is the wrong tool, and the README does not claim otherwise.

## How it differs from a printed system design book

The nearest comparison is a commercial system design text such as Designing Data-Intensive Applications or Alex Xu's System Design Interview volumes, which the README itself names when describing the HLD Handbook's scope. The difference in approach is not length. It is the correction model.

A printed book is fixed between editions, and errata accumulate in a place you have to go looking for. Here, a wrong claim is a pull request against a Markdown file, and the CI runs the same checks on that pull request as on any other. The README also states that the repository is the canonical content source for both books, so the website and the source cannot drift apart in the way a book and its companion site can.

The trade-off runs the other way too. A published book has an editor, a technical review pass and a named author accountable for each chapter. This project replaces that with a style guide, a contribution document and automated checks, which catch broken links and malformed frontmatter but not a confidently wrong explanation. If you need a single authority to cite for a design decision, a reviewed book is the safer reference; if you need something you can fork, translate or quote under a share-alike license, this is the better fit.

## License, citation and what upgrading costs

The license is CC BY-SA 4.0, declared in both the LICENSE file and the license field of package.json. For a reader, that means you can read, copy and adapt the text, including commercially, provided you give attribution and release derivatives under the same license. The share-alike clause is the part that catches people out: a chapter you adapt into an internal training document and then keep proprietary is not permitted by the license terms as written. That is a description of the license, not legal advice; if the use matters, ask a lawyer.

The repository also carries CITATION.cff, so there is a defined way to cite the handbooks in academic or internal writing.

Upgrade cost is close to zero in the usual sense, because there is no runtime dependency to upgrade. What you pay instead is re-reading cost. Because the content changes in place rather than through versioned releases, and no releases were retrieved for this repository, there is no changelog to diff between two points in time. Your only signal that a chapter changed is its date_updated frontmatter, read file by file. If you mirror the content into another system, you own the job of detecting drift.

For contributors, the ongoing cost is the check suite. Any edit has to pass lint, typos, citations, frontmatter, mermaid and links, plus the Vale prose rules, before it is mergeable. That is a real bar, and it is the reason the corpus stays consistent.

## Conclusion

Adopt it if you want a citable, forkable curriculum you can read on GitHub or at hld.handbook.academy and dsa.handbook.academy, and if you are willing to send corrections as pull requests. Do not adopt it expecting an npm package, a hosted course with progress tracking, or a course you can relicense as proprietary. Before relying on a chapter, open its file under content/ and check the date_updated frontmatter field, then run npm run check:all after your own edits.

## FAQ

### What is the Engineering Handbook?

It is a repository hosting two open-source curricula, the HLD Handbook and the DSA Handbook, as Markdown files under a CC BY-SA 4.0 license. The README describes the HLD book as 159 chapters across 12 parts plus a 22-page Trade-offs Library, and the DSA book as 120 chapters across 15 parts.

### Is the Engineering Handbook free to read?

Yes. The README states the books are free to read at handbook.academy, with the HLD curriculum at hld.handbook.academy and the DSA curriculum at dsa.handbook.academy, which the README labels a public beta. The repository license is CC BY-SA 4.0.

### Do I need to install anything to use the Engineering Handbook?

No. The content is Markdown under content/ and the README notes it renders natively on GitHub. Node 20 or newer and npm are only needed if you want to run the content checks or contribute, using the scripts defined in package.json.

### Which programming languages does the DSA Handbook cover?

The README states that Python is inlined in each chapter, while sibling sol.py, sol.java, sol.cpp and sol.go files cover 155 LeetCode problems, with the Java, C++ and Go solutions linked rather than inlined.

### How do I contribute a fix to the Engineering Handbook?

The README points contributors at CONTRIBUTING.md and STYLE_GUIDE.md, and states that pull requests to either handbook are welcome. The repository is the canonical content source for both books.

## Sources

- [handbook-academy/engineering-handbook on GitHub](https://github.com/handbook-academy/engineering-handbook)
- [Issues](https://github.com/handbook-academy/engineering-handbook/issues)
- [License: CC-BY-SA-4.0](https://github.com/handbook-academy/engineering-handbook/blob/main/LICENSE)
- [Project website](https://handbook.academy)
- [README](https://github.com/handbook-academy/engineering-handbook/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/handbook-academy-engineering-handbook