Orienting in a system you have never seen

The skill that quietly became the most valuable one

If review is the constraint, then the ability to understand an unfamiliar system quickly is the thing that relieves it. It is also the skill almost nobody is taught deliberately. People pick it up by accident over ten years, and the accident used to be reliable because everyone spent years in one codebase. That is less true now, and it is worth doing on purpose.

Here is a procedure. It takes about ninety minutes on a medium-sized service and it works whether the system was written by a person or generated last Tuesday.

1. Find the data model first, not the code

Before any source file, read the schema. \d+ in psql, the migrations directory, the ORM model files, the protobuf definitions, whichever exists.

The data model is the most honest document in any system. Code lies about intent, comments rot, README files describe the system somebody hoped to build. The schema describes what is actually stored, and every behaviour has to be expressible in terms of it. If there is a status column with five values, there are five states and somebody has to move rows between them. If there is a nullable deleted_at, deletion is soft and something must be filtering on it.

Write down, in five lines, what the main entities are and how they relate. If you cannot, you are not ready to read code yet.

2. Follow exactly one request end to end

Pick the most representative operation the system performs. Not the simplest, the representative one. Then trace it, by hand, from the outside in.

Route definition → handler → validation → the service or domain layer → the query → the response. Write down every file it touches, in order. Ten to fifteen files is normal; if it is fifty, that is itself the most important thing you have learned today.

This single trace gives you the architecture more reliably than any diagram, because a diagram shows the design and the trace shows the system.

3. Ask git where the system actually lives

Code is not uniformly important, and the repository knows which parts are.

# files changed most often in the last year
git log --since=1.year --name-only --pretty=format: \
  | sort | uniq -c | sort -rn | head -30

The top of that list is where the behaviour is, where the bugs are, and where your attention belongs. A file touched two hundred times in a year is either the core of the domain or a source of pain, and either way it is what you should read.

The inverse is also informative. A file untouched for four years is either stable or completely abandoned, and git log -1 on it usually tells you which.

4. Read the tests as documentation, with a caveat

Test names are the closest thing most systems have to a specification, and reading them in order is often faster than reading the code.

The caveat is new and it matters. In a codebase where tests were largely generated, the test names describe what the code does rather than what it should do, because that is what they were derived from. They are still worth reading (they tell you the intended shape), but they are no longer independent evidence of intent. Weight them accordingly: a test written before the code is testimony, a test written from the code is a summary.

5. Find the seams and the scary parts

Grep for the places where this system touches something it does not control:

rg -n 'http[s]?://|requests\.|fetch\(|boto3|stripe|kafka|redis' --type-add 'src:*.{py,ts,go,java}' -tsrc

Every external call is a place the system can be surprised. Then find the parts nobody wants to touch: git blame on the oldest untouched file, the module with a comment beginning “do not”, the function with a “# TODO: this is wrong but” attached.

The question that ends the exercise

When you think you understand the system, test it with one question, and answer it out loud before you check:

If I deleted this file, what would break, and how would I find out?

Pick three files: one you think is central, one you think is peripheral, one you are unsure about. Answer for each, then verify by searching for the imports. Being wrong here is the useful outcome: the file you thought was peripheral and turns out to be imported by forty modules is exactly the misunderstanding that would have made your next review worthless.

Doing this with a model, safely

This is a good use of a model and there is one rule. Ask it to describe, not to conclude. “Trace how a payment request flows through this repository and list the files in order” is verifiable in thirty seconds against the actual files. “Is this architecture good” is not verifiable at all and you will believe the answer anyway.

Check every file it names actually exists before you build anything on the answer. An invented module in an architectural summary is much harder to notice than an invented function in code, because nothing runs it.