code-explanation

Code Explanation

Produce a thorough written explanation of an entire repository so someone new can understand what it does, how it is built, and how the pieces fit together. The output is a CODE_EXPLANATION/ folder of markdown files: one OVERVIEW.md and a series of numbered deep-dive documents.

The goal is genuine understanding, not a file inventory. A good explanation reads like a knowledgeable engineer walking a new teammate through the codebase: it names the important abstractions, shows real code, and explains why things are shaped the way they are.

Workflow

1. Establish the structural map with treecap

Before reading any code, get a bird's-eye view of the repo layout. Use treecap, a tree viewer that caps how many entries it shows per folder so large repos stay readable.

Resolve the tool in this order:

1. treecap — preferred. Check with which treecap.
2. If it is missing, install it: pip install treecap (it is a PyPI package: https://pypi.org/project/treecap/). If pip isn't available, try pip3 install treecap or python -m pip install treecap.
3. If installation fails or is declined, fall back to tree (which tree).
4. If neither exists, fall back to a manual listing (e.g. find . -type f filtered sensibly), but prefer the real tools.

Run it on the target repo. Sensible defaults:

treecap -W 0 -L 3        # full width (all entries), 3 levels deep

-W caps entries shown per directory (0 = unlimited; the default is 5). -L caps display depth. Start broad, then re-run deeper or with a higher width on the directories that turn out to matter (e.g. treecap src -W 0). treecap skips .git, node_modules, __pycache__, and .venv by default, which is usually what you want.

Capture this tree — you'll embed a trimmed version of it in OVERVIEW.md.

2. Read the code and build a mental model

Now actually understand the repo. Don't write any explanation files until you have a real model of how it works. Investigate in roughly this order, because each step gives you vocabulary for the next:

• Entry points & manifests — package.json, pyproject.toml, Cargo.toml, go.mod, main.*, index.*, app.*, CLI definitions, server bootstraps. These tell you what the project is (library? service? CLI? web app?), its tech stack, and how it starts.
• Core data shapes — Pydantic models, dataclasses, TypeScript types/interfaces, ORM/DB schemas, protobufs, GraphQL schemas. These are the nouns of the system and the fastest way to understand the domain. They almost always deserve an early deep-dive file.
• Architecture & control flow — how requests/commands flow through the system, the major layers/modules and their dependencies, key design patterns.
• Major subsystems — each significant module, package, or feature area, one at a time.
• Cross-cutting concerns — config, auth, error handling, logging, persistence, external integrations.

Read the real source. Quote it later. If the repo is large, prioritize the code that carries the most meaning over exhaustively covering every file.

3. Create the CODE_EXPLANATION/ folder and write the docs

Create a CODE_EXPLANATION/ directory at the root of the repo being explained. Inside it, write OVERVIEW.md first, then numbered deep-dive files.

OVERVIEW.md

This is the front door. Include:

• What this project is — one or two paragraphs: purpose, what problem it solves, what kind of thing it is (service/library/CLI/app).
• Tech stack — languages, frameworks, key libraries, datastores.
• High-level architecture — a short narrative of how the major pieces fit, plus the trimmed treecap tree annotated with what each top-level directory/file is for.
• Reading guide — a table of contents listing every numbered file with a one-line description, so the reader knows where to go.

Numbered deep-dive files (01_*.md, 02_*.md, …)

Order them foundational-first, so each file builds on the previous. A typical-but-not-mandatory ordering:

• 01_architecture.md — the big picture: layers, modules, data/control flow, how a typical operation travels through the system end to end.
• 02_models.md (or 02_types.md / 02_data_model.md) — the core data structures (Pydantic models, TS types, schemas). These are foundational vocabulary, so explain them early.
• 03_*.md onward — each major subsystem/module/feature, one per file.
• Later files — cross-cutting concerns (config, auth, errors), key end-to-end flows, and how to run/extend the project.

Adapt the exact split and naming to the repo. A small CLI might need 3 files; a large service might need 10. Use descriptive slugs (04_auth_and_sessions.md, not 04_misc.md).

How to write the explanations

Explain code with real code. This is the core of the skill. For each important abstraction, show an actual excerpt from the repo (with a path/to/file.py:line-style reference), then explain what it does and why it matters. Prefer real snippets over invented pseudo-code. Trim long blocks to the revealing parts with # ... rather than pasting hundreds of lines.

The central request handler lives in `src/server/handler.py`:

```python
class RequestHandler:
    def __init__(self, store: Store, auth: AuthService):
        self.store = store
        self.auth = auth

    async def handle(self, req: Request) -> Response:
        user = await self.auth.verify(req.token)   # 1. authenticate
        record = await self.store.fetch(req.id)    # 2. load state
        return self._render(record, user)          # 3. shape response
```

Every inbound request flows through `handle()`: it authenticates the caller,
loads the relevant record, and renders a response. Note the dependency
injection in `__init__` — `Store` and `AuthService` are passed in rather than
constructed here, which is what makes the handler unit-testable.

Explain the why, not just the what. Point out design decisions, trade-offs, patterns, and non-obvious connections between files. "This uses a registry pattern so plugins can self-register at import time" is far more useful than "this is a dictionary."

Do not explain documentation or markdown. Existing docs, READMEs, changelogs, license files, and other prose are not the target — the code is. Don't summarize their contents. If they're worth pointing to, just list them briefly (e.g. a short "Existing documentation" section noting "docs/api.md — API reference; CONTRIBUTING.md — contributor guide") so the reader knows they exist, and move on.

Write for a capable newcomer. Assume the reader is a competent engineer who has never seen this repo. Define project-specific jargon. Use diagrams in fenced code blocks (ASCII or mermaid) when a flow or hierarchy is easier shown than told.

Be accurate. Only describe code you've actually read. If something is unclear or you're inferring, say so rather than inventing behavior.

Quick checklist

• Resolved a tree tool (treecap preferred, installed if missing, else tree)
• Captured the repo structure
• Read entry points, core models/types, and major modules before writing
• Created CODE_EXPLANATION/ at the repo root
• OVERVIEW.md with purpose, stack, architecture, annotated tree, and a TOC
• Numbered files, foundational-first (architecture/models early)
• Real code excerpts with file references throughout
• Explained the why, not just the what
• Docs/markdown listed, not explained