About Semicolony

Semicolony explains how the systems behind software work: databases, networks, operating systems and distributed systems. It is written for working software engineers, for people preparing for system design interviews, and for anyone who wants to know what happens after a request leaves the browser.

The site is made by one person, Nilesh, a backend and distributed systems engineer, with a lot of help from AI. How that works is set out below. It is free to read and needs no account.

The four sections

  • Codex

    Study paths on databases, networking, operating systems, distributed systems, languages and more.

  • How it works

    Explanations of one system at a time, such as DNS, TCP, Kafka or a load balancer.

  • Simulators

    Models that run in the browser, so you can watch a B-tree split or a Raft election happen.

  • Roadmaps

    Suggested reading orders for backend, system design, DevOps, security and other roles.

How pages are written

The rules every page is written and kept to, whoever or whatever drafted it.

  1. 1
    Sources are named

    Guides start from primary material: the RFC, the paper, the project’s documentation or its source code. Pages link to what they used, and a claim that can’t be traced to a source is taken out.

  2. 2
    Numbers are real or labelled

    A figure for latency, throughput or failure rates either links to where it came from or says it is a rough estimate. Every number a simulator shows is computed by the simulation itself.

  3. 3
    Simulators are tested

    The code behind a rebuilt simulator is kept apart from the page so it can be run on its own and compared with a reference: a brute-force version of the same algorithm, a worked example from the source, or the real tool’s output. Those tests run whenever the simulator code changes, and the page lists what they check.

  4. 4
    Review status is shown

    Each article says at the top whether I have reviewed it by hand. Pages that haven’t been reviewed yet say so.

  5. 5
    Dates come from the edit history

    Pages show when they were first published and when they last changed, both read from the site’s git history. Typo and layout fixes do not change the date.

  6. 6
    Mistakes get fixed

    Select text on any article and a “Suggest a fix” button appears. Corrections are read and, when they hold up, the page is updated.

  7. 7
    Everything runs in your browser

    There are no accounts. Simulators run in the page, and reading progress is kept in your browser’s local storage.

Who makes it

I’m Nilesh, a backend and distributed systems engineer based in Bengaluru. Most of my work is in Go, Rust, Kubernetes and AWS, and the parts of systems I like most are the ones this site spends the most time on: consensus, replication, partitioning and the storage underneath them.

Semicolony is a solo project. There is no team and no editorial staff behind it. Earlier versions of the site signed pages “Semicolony staff”, which suggested otherwise; pages now carry my name once I have reviewed them myself, and say plainly when I haven’t.

How AI is used

Most of the text and code on this site was drafted with AI models, mainly Anthropic’s Claude, working from my instructions and from the sources each page links to. I pick the topics, set the rules listed above, and decide what gets published. One person could not have written this many pages without it.

AI drafting is fast, and it also makes confident mistakes. So the site tries not to ask for your trust:

  • Pages link to the RFC, paper, documentation or source code they rely on. On the rebuilt simulator pages, every claim was checked against those sources and anything that couldn’t be traced was taken out.
  • Simulator logic is tested against references that don’t depend on the AI being right: a brute-force version of the same algorithm, a worked example from the textbook or RFC, a closed-form result, or the real tool’s output. 82 simulators have tests so far. Each lists its checks under the byline and links to the test code, and the tests run on every change.
  • Every article shows whether I have reviewed it by hand. 1 page has been reviewed so far, starting with the most-read ones.

What “reviewed” means

A page whose byline names me and gives a review date has been read by me from start to finish, its claims checked against the sources it links, and its simulator tried by hand. Anything wrong was fixed before the mark went on, and the date next to it is the day of the review.

A page that says “Not yet reviewed by hand” was drafted with AI and I haven’t read it through yet. If it has a simulator with tests, the byline says so. Read it the way you would read a well-sourced draft, and if you find a mistake on any page, reviewed or not, please tell me.

How the site is paid for

The site shows no ads and has no paywall at the moment. Hosting is paid for out of pocket. Ads from Google AdSense may be added later; if they are, they will be labelled, placed between sections rather than inside a simulator or a code sample, and there will be no pop-ups or autoplay video.

The privacy policy lists what analytics and advertising collect and how to opt out.

Contact

Email [email protected], or [email protected] for mistakes. The contact page covers removal requests and other questions. The site is also on X as @semicolonydev.