KeyanVakil/codebase-map

Build a map before you start digging.

Steps

1. Read these files first (in order):

   • README.md, CONTRIBUTING.md, CLAUDE.md (if present)
   • package.json / pyproject.toml / go.mod — dependencies reveal a lot about the architecture
   • Entry point files: main.*, index.*, app.*, server.*
   • Config files: .env.example, docker-compose.yml, vercel.json, railway.json

2. Read a representative sample of source files — at least one from each top-level directory under src/ or app/.

3. Produce the map in this format:

---

What this does

One paragraph. The product/tool in plain English.

How to run it

The minimum commands to get it running locally.

Architecture overview

[Request/Event]
      ↓
[Entry point] (file:line)
      ↓
[Key layer 1] — what it does
      ↓
[Key layer 2] — what it does
      ↓
[Data store / external service]

Key files & what they own

File/Directory	Owns
src/...	...

Core abstractions

The 3–5 concepts you must understand to work in this codebase. For each: name, what it is, where it's defined, and what depends on it.

Data model

The main entities and how they relate. A simple list of tables/types + their key fields is enough.

Gotchas & non-obvious things

• Things that will bite you if you don't know them
• Naming inconsistencies, historical weirdness, "don't touch X" areas
• Places where the code lies (the abstraction doesn't match the implementation)

Where to make changes

For common tasks in this codebase, where to look:

• Add a new API route → ...
• Add a new UI page → ...
• Change the data model → ...
• Add a background job → ...

---

Rules

• Prioritize accuracy over completeness — if you're not sure about something, say so
• The map should fit in one screen — link to files rather than quoting them
• Update the map if you discover it's wrong while working