How to understand a new codebase

A method you can follow on any repository, in the order that saves the most time.

Reading a new codebase top to bottom does not work. A repository of a few hundred files has no natural reading order, and most of it is not relevant to the change you have been asked to make. What works is a sequence of small questions, each of which gives you a fixed point to hang the next one on.

1. Read the README, then run the thing

Start with the README, but treat it as a claim, not a fact. Follow its install and run instructions exactly. Note every step that fails or that the README does not mention. Those gaps are your first findings, and they are also the questions the next person will ask you.

If you can run the program, you now have something better than text: a working system you can poke. If you cannot, find out why before reading any further, because every later step is easier with a running example.

2. Find the entry points

Programs start somewhere. Look at the manifest (pyproject.toml, package.json, go.mod, Cargo.toml, a Dockerfile) for the declared commands and the main module. Then look for the usual names: main.py, app.py, server.ts, cmd/, a Procfile. For a web service, find where the routes are registered. For a command-line tool, find where the arguments are parsed.

Write the entry points down. A typical repository has two or three: a server, a command-line interface, a background worker.

3. Trace one request all the way through

Pick one concrete thing the program does, such as "a user submits the sign-up form" or "the nightly job exports a report". Follow it from the entry point to the last side effect: which function receives it, what it validates, which module does the real work, where data is read or written, what is returned.

Do this with a debugger or with log lines if you can, and with search if you cannot. One traced path teaches you the layering, the naming habits and the error handling of the whole project, because the rest of the code was written by the same people in the same style.

4. Read the tests

Tests are the only documentation that fails when it is wrong. Skim the test names first; a good suite reads like a list of behaviours. Then read two or three tests closely, especially ones that cover the path you traced. They show you how the authors build the objects they care about and what they consider correct.

Also note what is missing. An area with no tests is an area where changes are more risky, and where the next bug is likely to come from.

5. Map the modules

Now zoom out. List the top-level folders and write one sentence for each: what it is for, and what it depends on. Use the import statements to find the dependencies. You are looking for the shape: layers that only call downward, a shared utilities folder that everything imports, a cycle that should not exist.

Sketch this on paper or in a diagram tool. If you cannot describe a folder in one sentence, read its entry file and its tests, and try again.

6. Check what anyone tells you against the code

Whoever explains the code to you, whether a colleague, an old wiki page or an AI assistant, can be wrong, and the most dangerous errors are plausible ones: a function that was renamed two years ago, a module that no longer exists, a setting that the code never reads. Before you rely on a statement, find the line that proves it. Search for the exact name. Open the file. Check that the function does what is claimed, at the version you are working on.

This habit costs a minute per claim and prevents days of working from a wrong picture. It applies to generated documentation too.

7. Write down what you learned

Keep notes as you go: the entry points, the traced path, the module map, the questions you could not answer. When you finish, you have the start of the onboarding document that the repository was missing. Put it in the repository, next to the code, so that it changes with the code.

Where RepoLantern fits

RepoLantern does a first pass of steps 2, 5 and 6 for you. It reads the whole repository at one commit, writes a guide with architecture diagrams and a module reference, links its claims to exact lines of code, and checks every file, function and class name it mentions against the repository. Names it cannot find are listed at the end of the guide, so you know what to verify by hand. It does not replace running the program or tracing a request yourself. How the pipeline works and how the checks are tested are described in detail, and the documentation covers each step of making a guide.