Strategic Codebase Navigation

Strategy 2: Boundary & Registration Tracing

Use when: You need to understand the high-level architecture — how modules connect, what the extension points are, how things get wired together.

1. Find the "Glue" code — large systems use registration patterns, not direct calls.

   • Search for keywords: Register, Factory, Provider, Manager, Plugin, Module, Handler, Middleware.
   • Use grep_search with patterns like register, factory, createModule, addPlugin.

2. Identify the Contract — find the interface or abstract class that modules must implement.

   • Look at what the registration function accepts. That's the contract.
   • Use view_code_item to inspect the base class or interface.

3. Map the Lifecycle — trace when modules are loaded vs. initialized.

   • Search for initialization sequences: init, setup, bootstrap, configure.
   • This reveals the true dependency graph (load order = dependency order).

4. Document what you find using the Architecture Discovery Report template below.

Strategy 3: Structural Pattern Matching (Clone & Mutate)

Use when: You need to add something similar to what already exists (new endpoint, new command, new module).

1. Find the closest existing example — search for a feature similar to what you're building.

   • Use find_by_name and grep_search to locate similar modules, handlers, or components.

2. Analyze its registration — how does the existing feature register itself with the system?

   • What files does it touch? What config entries does it need? What interfaces does it implement?

3. Copy the structure — duplicate the existing feature's files.

4. Swap the internal logic — replace the business logic while keeping the registration boilerplate identical.

5. Verify registration — confirm the new module is picked up by the system the same way the original was.

Strategy 4: Metadata & Module Auditing

Use when: Planning a migration, mapping the full dependency graph, or understanding which modules can be changed safely.

1. Start with build configuration — treat package.json, Cargo.toml, build.gradle, CMakeLists.txt, etc. as your schematic.

   • Use find_by_name to locate all build/config files.

2. Classify modules:

   • Leaf modules — no other modules depend on them. Safe to change or migrate first.
   • Core modules — many modules depend on them. Change last, with extreme care.
   • Use grep_search to trace imports/dependencies between modules.

3. Start from the leaves — migrate or refactor leaf modules first, working inward toward the core.

4. Map side effects — identify where code touches databases, APIs, file systems, or external services. These are your risk boundaries.

Architecture Discovery Report Template

Fill this out when first analyzing a new codebase.

# Architecture Discovery Report: [Project Name]

## 1. System Core
- **Core Module Location:** [Path]
- **Primary Responsibility:** [e.g., Data routing, Engine kernel]
- **Evidence:** [List modules depending on this Core]

## 2. Registration Contract
- **Registration Manager:** [e.g., ModuleManager.cpp, registry.py]
- **Base Interface/Class:** [The class business logic must inherit from]
- **Required Boilerplate:**
    - [ ] Method: [Name]
    - [ ] Registration call: [Example]

## 3. Dependency Hierarchy
- **Leaf Modules (safe to change first):** [Modules with no incoming deps]
- **Core Modules (change last):** [Modules everything depends on]

## 4. Side-Effect Boundaries
- **I/O & Persistence:** [Filesystem, Database classes]
- **Network/API Layer:** [Socket handlers, REST clients]
- **External Services:** [Third-party APIs, message queues]

## 5. Smallest Verification Test
- **Test Location:** [File path]
- **Proposed Change:** [e.g., Change a log string]
- **How to verify:** [How to see the change in the live app]

Reference

• Source Material: Navigating Large Codebases — Instructor's Guide with Marc Olano
• Primary URL: https://www.youtube.com/watch?v=YZdVfKJNLfk