1. LandOffer
  2. Blog
  3. All articles
  4. Joining an Unfamiliar Codebase: Build a System Map Before Reading Everything

Onboarding & Teamwork

Joining an Unfamiliar Codebase: Build a System Map Before Reading Everything

A completed map of an original local note-index fixture links entry points, transformations and output boundaries to four actual runs and a corrected error-path explanation.

10 min readLandOffer team

Join an unfamiliar codebase by tracing one important user action from its entry point to its observable result. Map the components, data boundaries and failure paths involved, then attach evidence and unanswered questions to that map. Choose the next file from a question the map leaves unanswered. Reading every directory in order is rarely necessary to explain one bounded workflow.

This LandOffer.ai guide uses an original, deliberately small Python fixture written for this article. Its four local command-line runs were executed with Python 3.9.6 on October 25, 2026. The observations concern that fixture only. No employer repository, production service, editor navigation feature or deployment was tested, and the conceptual illustrations are not diagrams of an actual organization.

Two colleagues trace one red route through an open architectural model while other rooms remain unexamined

Choose a journey before opening every module

Start with an outcome a user or another system needs: create an invoice preview, save a draft, import a local file or generate a report. Ask where that action begins, which information changes along the way, where persistent state is read or written, and how someone knows it succeeded. Keep the first question narrow enough to follow through.

For the teaching fixture, the journey is “turn a local JSON list of notes into a categorized HTML index.” It has three source modules: cli.py, notes.py and page.py. The input contains synthetic titles and categories; the output is one local file. There is no network service, database, authentication layer or background worker in this fixture.

That small boundary makes the method inspectable. A real codebase may have several entry points, queues, feature flags, databases and deployment units. Record those when you find them; do not add them because an architecture diagram normally has those boxes. Conversely, failing to see a database import in one file does not establish that a real system has no storage dependency elsewhere.

Read repository instructions, setup notes and the relevant ownership information before running anything. Confirm the intended environment and side effects. In this case, the command can overwrite its named output file, so the observed runs use disposable destinations inside the fixture directory. That choice avoids treating exploration as permission to modify production state.

GitHub's code-navigation documentation describes jumping between symbol definitions and references. Use those relationships to follow the selected journey. A search result identifies a place to inspect; it does not, by itself, prove that the selected runtime path calls it.

Start at the command, route handler, scheduled job or event consumer that initiates the action. Find the function it calls and inspect its inputs and return value. Follow the important data transformation rather than every helper encountered. Then search references in the other direction to see whether the same function also serves a different workflow.

In this fixture, cli.py imports load_notes and group_notes from notes.py, and render_index from page.py. Those imports establish source relationships. Reading main() establishes the call order: load, group, render, then write. The filesystem write is in the entry module, so describing page.py as the storage layer would be inaccurate.

VS Code's code-navigation guide documents definition, reference and symbol navigation. Available semantic information depends on the relevant language support and project setup. This article did not exercise those editor features. If navigation is incomplete, combine text search with direct inspection instead of treating an empty reference panel as proof that a function is unused.

Keep a short trace note as you go: the symbol, its input, its output and the evidence for the next edge. Another reader should be able to retrace the route without repeating your entire search. A function named save may prepare a request rather than persist anything; names are clues that still need checking against implementation and the applicable runtime path.

Worked asset: a completed map of the note-index journey

The fixture's input contains three notes: “Harbor sketch” and the literal title <em>Unfinished</em> in Drawing, plus “Clay study” in Sculpture. The markup-like title is synthetic text used to inspect output handling, not a request to execute HTML.

The completed map below combines direct source inspection with the bounded runtime observations described afterward. Module and function names refer to the actual original fixture saved with this draft.

Component or boundary Role in this journey Evidence and remaining limit
cli.py:main Parses input/output paths and coordinates loading, grouping, rendering and writing Direct call sequence inspected; no claim that every possible invocation was exercised
Input file → notes.py:load_notes Reads UTF-8 JSON; requires an array whose items contain string title and category fields Valid sample and one missing-category input executed; exhaustive schema validation was not established
notes.py:group_notes Collects titles into category groups, retaining the supplied order within each group Source inspected; sample produces two Drawing titles and one Sculpture title
page.py:render_index Sorts category names and constructs HTML sections and list items Source inspected and output examined; this fixture does not use a separate template engine
Text → HTML Escapes category names and titles when inserting them into markup Literal markup-like title observed as escaped text in the generated file; not a complete security assessment
Rendered string → output file main writes the completed page using UTF-8 after the input-processing block Valid run writes one file; output-write errors are outside the handled input-error branch
Filesystem and standard library JSON parsing, argument handling, grouping, escaping and local file operations Source imports inspected; no external package or remote service is required for these runs

The map is selective without being vague. It says where persistence occurs, identifies a transformation that affects visible output, and names a meaningful error boundary. It does not contain invented services merely to make the architecture appear substantial.

The working route is main → load_notes → group_notes → render_index → write_text. The names alone would conceal two important details: group_notes preserves within-category order while render_index sorts categories, and the output write occurs after the exception handler. Use those details to decide whether the next question belongs in grouping, rendering or output handling.

Check one result and one failure branch

Reading gives you an explanation to check. A bounded execution can confirm a particular path and expose a mistaken assumption, but it does not establish complete system behavior. Record the runtime version, exact input, exit code, standard output or error, and the resulting file or absence of a file. Preserve evidence that contradicts the first map.

For the valid fixture run, the command is:

python3 cli.py sample.json observed-index.html

It exits with code 0 and reports that it wrote three notes. Direct inspection of the saved HTML finds two category headings and three list items; this check did not open a browser. Drawing appears before Sculpture; its two titles retain their input order. The title containing <em> is emitted as &lt;em&gt;Unfinished&lt;/em&gt;, rather than being inserted as an emphasis element. This is an observed output check, not a claim about a browser rendering test.

The invalid input contains a note with a title but no category. That run exits with code 2, prints Input rejected: note 0: title and category must be strings, and creates no new output file. A separate run against an existing disposable file leaves its sentinel contents unchanged. These observations support the input-rejection branch for this specific invalid record.

Finally, a valid input directed to a missing output directory fails with FileNotFoundError. It does not follow the handled Input rejected path because write_text is outside that try block. The important discovery is a narrower error-handling boundary than someone might infer from the entry point's exception handler.

No repair was implemented to make the example look more complete. The fixture still has that boundary, and its map records it. Whether to create directories, improve error wording or reject an output path is a separate design question with requirements that this exploration has not established.

A route sketch and architectural model retain a stopped path at a missing doorway beside the traced working route

Worked asset: revise the map when evidence disagrees

A useful map records how confidence changed. Here is the completed observation register for the four actual runs. “Supported” refers to this input and execution, not all inputs or an employer's application.

Initial question Actual local observation Map correction or retained question
Does the selected command reach a file output? Valid sample exits 0 and creates HTML with three note items in two categories Supported for this journey; output persistence belongs to main, not the rendering module
Does an invalid record stop before a new output is written? Missing category exits 2 and leaves the new destination absent Record validation before writing for this case; other input failures need their own evidence
Does that same invalid record replace an existing output? Disposable sentinel file remains byte-for-byte unchanged Record the preserved-output observation for the rejected input; do not generalize it to interrupted successful writes
Are output failures handled like input failures? Missing output parent produces an unhandled FileNotFoundError Split the error paths on the map; output error handling remains a separate follow-up question

The register narrows a statement such as “the CLI handles file errors” to the specific input and output branches actually examined. It also avoids the opposite error of treating one uncovered branch as proof that every part of the program is broken. A small observation should lead to a proportionate conclusion.

Keep static and runtime evidence distinguishable. Source inspection establishes where the code places the handler. The failed output run establishes what happened for the missing-directory case. Neither proves what a larger application should do, whether a deployment wrapper creates directories, or whether an operating environment changes the path behavior.

Ask maintainers questions attached to the map

In a real onboarding conversation, show the traced journey and ask about the boundaries you could not establish. “Is this the entry point used in production, or does another wrapper call it?” is more actionable than “Can you explain the whole backend?” Ask which user flows share the touched module and which owner can confirm the intended contract.

For a note-index tool like the fixture, useful questions would include whether category order is part of the user-facing contract, whether writes should replace an existing file, and how output failures should be reported. These are questions to an appropriate owner, not decisions granted to the newest engineer by drawing a map.

Google's engineering code-review guidance asks reviewers to understand how pieces interact and inspect a change in its surrounding context. Although that page addresses review, the same reading habit is useful during onboarding: inspect enough of the surrounding code to understand the selected path before proposing a change.

Record a maintainer's answer beside the relevant edge, with the version or context it applies to. If the explanation conflicts with observed behavior, retain both until the difference is resolved. The explanation may describe another entry point, an intended future state or an environment the local run did not reproduce.

Stop when the map supports the next bounded task

The first map is useful when you can explain the journey, locate its main transformations and state what remains unknown. That is a better stopping condition than reaching an arbitrary percentage of files read. Choose the next module because a concrete question leads there, and keep unrelated areas visibly outside the current map.

For this fixture, the next design discussion concerns output failure handling and the file-write contract. It does not require exploring imaginary authentication or deployment systems. For a real repository, the next task may instead expose a genuine queue, permission boundary or external service that expands the map.

Visit LandOffer.ai for more engineering workplace guides. Before your next onboarding discussion, bring one traced user action, the files and observations supporting each important edge, and two unresolved questions for the people who own those decisions. Ask which edge needs correction and which unknown matters for your next assigned task. Save those answers beside the current map.

Sources and Further Reading