# How System Design Concepts Are Organized in the liquidslr/system-design-notes Repository

> Explore how the liquidslr system design notes repository structures concepts into modular directories with co-located assets for an effective learning path.

- Repository: [Gaurav Kumar/system-design-notes](https://github.com/liquidslr/system-design-notes)
- Tags: how-to-guide
- Published: 2026-09-11

---

**The liquidslr/system-design-notes repository organizes system design concepts into numbered, self-contained directories with co-located documentation and visual assets, creating a modular learning path from foundational scaling principles to advanced architectural patterns.**

The `liquidslr/system-design-notes` repository employs a hierarchical, modular layout to catalog system design knowledge. This systematic approach groups each concept into isolated directories that combine explanatory text with supporting diagrams, making the collection both navigable and maintainable. Understanding how these **system design concepts are organized** helps developers locate specific patterns quickly or follow the suggested educational progression from basic to advanced topics.

## The Numeric Prefix Convention

Every concept folder begins with a two-digit number (e.g., `01.`, `02.`) followed by a descriptive title. This prefix defines a logical ordering that suggests a learning path while allowing quick scanning of the table of contents in GitHub’s file tree.

Key directories following this convention include:

- `01. Scaling/` – Foundational horizontal and vertical scaling concepts
- `02. Back Of the Envelope Estimation/` – Capacity planning fundamentals
- `04. Rate Limiter/` – Token bucket and leaky bucket implementations
- `06. Key-Value Store/` – Data replication and consistency strategies
- `13. Search Autocomplete/` – Trie structures and sharding techniques

The numeric sequence implies a pedagogical flow, starting with basics like `01. Scaling/Readme.md` and progressing toward complex systems such as `13. Search Autocomplete/Readme.md`.

## Modular Documentation Architecture

### Self-Contained README Files

Inside each numbered directory resides a [`Readme.md`](https://github.com/liquidslr/system-design-notes/blob/main/Readme.md) file that serves as the canonical source for that topic. According to the repository structure, these files contain high-level overviews, design decisions, architectural diagrams, and step-by-step implementation guidance. For example, `04. Rate Limiter/Readme.md` demonstrates specific design patterns, while `06. Key-Value Store/Readme.md` explores data replication strategies.

### Co-Located Visual Assets

Supporting diagrams, charts, and illustrations are stored in an `images/` subdirectory under the same folder as the documentation. This co-location ensures that visual aids remain synchronized with their corresponding text, simplifying updates and keeping related assets together. When viewing `01. Scaling/Readme.md`, the associated architecture diagrams reside in `01. Scaling/images/`.

## The Master Index

The repository root contains a [`Readme.md`](https://github.com/liquidslr/system-design-notes/blob/main/Readme.md) that functions as the master index, linking to each numbered concept. This central navigation hub mirrors the folder structure precisely, allowing readers to jump directly to specific topics via curated links or explore the directory tree directly. The root [`Readme.md`](https://github.com/liquidslr/system-design-notes/blob/main/Readme.md) effectively serves as the entry point that maps the numeric ordering to human-readable descriptions.

## Programmatic Repository Navigation

The predictable naming convention enables automated tooling and static site generation. The following Python script demonstrates how to parse the repository structure to generate a programmatic index:

```python
import os
from pathlib import Path

# Base path of the cloned repository

BASE = Path("/path/to/system-design-notes")

def list_topics():
    """Return a list of (order, title, readme_path) for each topic."""
    topics = []
    for entry in sorted(BASE.iterdir()):
        if entry.is_dir() and entry.name[:2].isdigit():
            order = int(entry.name[:2])
            title = entry.name[3:]          # strip "NN. " prefix

            readme = entry / "Readme.md"
            if readme.exists():
                topics.append((order, title, readme))
    return topics

def print_index():
    for order, title, readme in list_topics():
        rel = readme.relative_to(BASE)
        print(f"{order:02d}. [{title}]({rel})")

print_index()

```

Running this script against the `liquidslr/system-design-notes` repository produces a structured index that mirrors the manual organization, useful for generating navigation menus or documentation sites without hard-coding paths.

## Summary

- **Numeric prefixes** create a logical ordering system (01-NN) that suggests a learning progression from fundamentals to advanced patterns.
- **Self-contained modules** isolate each topic in its own directory with a dedicated [`Readme.md`](https://github.com/liquidslr/system-design-notes/blob/main/Readme.md) and co-located `images/` subdirectory.
- **Master index** at the root [`Readme.md`](https://github.com/liquidslr/system-design-notes/blob/main/Readme.md) provides centralized navigation to all concepts.
- **Consistent naming** allows programmatic parsing and automated documentation generation.

## Frequently Asked Questions

### Why are the folders prefixed with numbers?

The two-digit numeric prefix (e.g., `01.`, `02.`) establishes a logical ordering for the system design concepts and enables quick scanning of the table of contents. This convention suggests a recommended learning path while keeping the directory listing sorted correctly in file explorers and GitHub’s interface.

### Where are architectural diagrams stored within each topic?

Visual assets reside in an `images/` subdirectory inside each concept folder. For example, diagrams supporting `04. Rate Limiter/Readme.md` are stored in `04. Rate Limiter/images/`, ensuring documentation and illustrations remain co-located and synchronized.

### How does the root README.md function in this organization?

The root [`Readme.md`](https://github.com/liquidslr/system-design-notes/blob/main/Readme.md) serves as the master index that links to every numbered concept directory. It mirrors the folder structure’s numeric ordering, providing a centralized navigation hub that allows readers to jump directly to specific topics like `06. Key-Value Store` or `13. Search Autocomplete`.

### Is there a recommended order for studying these system design concepts?

Yes, the numeric prefix suggests a learning path that begins with foundational ideas in `01. Scaling/` and progresses through estimation techniques, rate limiting, and storage systems, eventually reaching advanced patterns like search autocomplete systems in `13. Search Autocomplete/`.