How to Read a Repository

Do not begin by reading files in directory order. Begin with a concrete operation and construct the smallest map that can explain it.

Establish the revision

Record the commit, enabled features, and relevant runtime. Repository behavior can change while filenames remain familiar.

git rev-parse --short HEAD
cargo metadata --no-deps

Find the public boundary

Start with one thing a user can do:

sqlx::query("SELECT id FROM users")
    .fetch_one(&pool)
    .await?;

Identify the public function, the value it constructs, and the method that causes work to begin. This creates a path through the repository instead of a list of unrelated modules.

Build two maps

The static map shows crates and dependencies:

The dynamic map shows what happens over time:

Do not combine these too early. A crate dependency graph and a request sequence answer different questions.

Follow state, not only function calls

At each step, record:

• the important value;
• who owns it;
• whether it is borrowed mutably or shared;
• which state transition occurs;
• where an error or cancellation can interrupt the transition.

A function-call trace explains control flow. A state trace explains why the API has its shape.

Read bounds as architecture

Translate generic bounds into concrete statements. For example:

E: Executor<'c, Database = DB>

means the executor and query must agree on one database implementation. The bound is not incidental compiler syntax; it prevents a PostgreSQL query from being executed by a MySQL executor.

Verify the map

Search for every implementation of the important trait, inspect the cleanup path, and check at least one test or example. A trustworthy map includes the unhappy path and names the source locations that support it.