# How to Learn an Existing Codebase

> A first week that works when you inherit software: what to read first, the questions to answer before changing anything, how to read code with evidence instead of assumptions, and where documentation lies.

Inheriting a codebase is the most common engineering situation and the least taught. It happens when you join a team, when a contractor leaves, when a side project comes back to life, and now most often of all, when an AI hands you a finished application.

The instinct is to start reading at the top of the largest file. This is a better plan.

## Start from behaviour, not from code

Before you open the editor, use the thing. Click through it, send it a request, look at what it stores. Ten minutes here saves hours of reading the wrong module.

- What does it do for the person who uses it?
- What are the two or three actions that matter most?
- What data does it hold that would be painful to lose?
- What is it connected to that you do not control?

You are looking for the shape of the thing. Code makes sense in relation to a purpose, and until you have the purpose, every file is equally plausible.

## Find the doors

Every system has a small number of entry points: HTTP routes, scheduled jobs, queue consumers, command-line entries, webhooks. They are the skeleton, and there are usually fewer than you fear.

Pick the single most important one and trace it end to end, naming every file the request passes through. When you can do that from memory, you are no longer lost, whatever percentage of the code you have not read.

## Answer these before you change anything

1. How does it run locally, and what does it need that is not in the repository?
2. Where does configuration come from, and what changes between local and production?
3. What is the data model, and which records are load-bearing?
4. How does the system decide who is allowed to do something?
5. What happens when the thing it depends on is slow or absent?
6. How does code get to production, and how would you undo it?
7. What is tested, and what is only believed to work?

These seven answers are the difference between a change you can defend and a change that happens to work.

## Read with evidence, not assumptions

Reading code is a slow way to learn what code does. Running it is faster and more honest.

- Add a log line and watch the actual path, rather than deducing it.
- Break something small on purpose in a copy and see what notices.
- Query the database directly and compare it with what the screen claims.
- Time the important request before you have an opinion about performance.

> Do this on a copy. The whole method depends on being free to break things, which is exactly why LoWisa teaches from a safe sandbox copy of the project rather than from your original.

## Where documentation lies

Written documentation records what someone believed on the day they wrote it. Treat it as a witness statement, not as evidence.

- A README describes the intended setup. The pipeline configuration describes the real one.
- Comments describe intent. Tests describe behaviour someone cared enough to pin down.
- Architecture diagrams age badly. Dependency graphs generated from the code do not.
- Naming lies quietly: a module called `utils` is where decisions go to hide.

## Doing this with LoWisa

The method above is what the tutor automates in the parts where a person is slow and keeps manual in the parts where doing it yourself is the point.

1. **Open the project.** It is copied into a safe sandbox and scanned before anything is explained.
2. **Take the walkthrough.** System Immersion covers what it does, how it is organised, entry points, data flow and how the parts connect, drawn on a whiteboard as it talks.
3. **Score it.** Your project is measured against 25 ownership areas across 7 categories, and the gaps are sequenced by what will teach you the most.
4. **Work in the sandbox.** Break, fix and verify with terminal commands run beside you, so claims are checked rather than believed.
5. **Prove ownership.** Explain the system back. A hole in the explanation becomes the next lesson.

## A two-week plan that works

| When | What you do | What you should be able to say |
| --- | --- | --- |
| Day 1 | Use the product, list the entry points, get it running locally | "Here is what it does and here is how it starts" |
| Days 2 to 3 | Trace one important request end to end, read the data model | "Here is the path a record takes" |
| Days 4 to 5 | Follow configuration, permissions and deployment | "Here is who is allowed to do this, and here is how it ships" |
| Week 2 | Break things in a copy: failure paths, load, dependencies | "Here is what fails first, and why" |
| End of week 2 | Make one small change with a prediction written down first | "I said what would move, and it moved" |

Two weeks is a realistic target for being useful on a system of ordinary size. Being the person others ask takes longer, and comes from the same loop repeated.

## Keep learning away from the desk

The reading that supports this, databases, deployment, testing, security, is where the phone app fits. It is on Google Play, teaches lesson by lesson with the tutor writing and speaking each lesson, and has learning cohorts if you would rather do it with other people than alone.

## Frequently asked questions

### How long does it take to learn a codebase?

Useful in about two weeks for a system of ordinary size, if you work from behaviour and entry points rather than reading top to bottom. Confident ownership of the operational areas takes longer and is best done one area at a time.

### Should I read the whole codebase?

No. Read the entry points, one full request path, the data model and the code that decides resources, permissions and failure. The rest can be read when it becomes relevant.

### What if there are no tests and no documentation?

Then the running system is your documentation. Add logging, trace one path, and write the first test as a way of recording what you learned. That test is worth more than the document you were wishing for.

### What if the codebase was generated by AI?

Same method, with one addition: run an audit first, because generated projects tend to be locally correct and globally silent about traffic, failure and trust.

### What does LoWisa cost?

Downloading is free and starts with 20 credits, awarded once on first install. LoWisa Starter is $8 a month with 200 credits included, LoWisa Plus is $11 a month with 500 credits included. A credit is one cent of AI, billed at exact provider cost.

## Open the project you inherited

Let the tutor build the map, then work through the gaps in the order that teaches you most.

---

Source: https://lowisa.dev/learn/learn-existing-codebase/ · Updated 2026-09-10