Exploring an Unfamiliar Codebase

Learn how to quickly get oriented in a new codebase using noodlbox's navigation resources and search tools.

Scenario

You've just joined a project and need to understand:

How the code is organized
Where to find specific functionality
How different parts interact

Tools & Resources

Codebase Map - Overview
Community Detail - Deep dives
Context Search - Finding specific code
Cypher Query - Custom queries

Step-by-Step Workflow

Step 1: Get the Big Picture

Start with the codebase map:

GET map://my-app

This shows:

All communities (functional areas)
How many symbols in each
How communities connect

What to look for:

High cohesion communities (well-designed)
Major cross-flows (key dependencies)
Community names (hint at functionality)

Step 2: Identify Your Area of Interest

Find communities related to your task:

const map = await getResource('map://my-app');

// Looking for authentication code
const authCommunities = map.communities.filter(c =>
  c.label.toLowerCase().includes('auth') ||
  c.key_symbols.some(s => s.includes('auth'))
);

Step 3: Explore the Community

Deep dive into the relevant community:

GET map://my-app/community/{community-id}

Focus on:

Entry points (where to start reading)
Key symbols (most important functions)
Processes (execution flows)

Step 4: Search for Specifics

Use context search to find exact code:

{
  "repository": "my-app",
  "q": "user authentication login",
  "task_context": "Learning authentication system",
  "current_goal": "Understand how users log in",
  "search_intention": "Find login implementation"
}

Step 5: Trace a Process

Follow an execution flow:

GET map://my-app/process/{process-id}

See exactly which functions are called in order.

Step 6: Query for Details

Use Cypher to answer specific questions:

// Find all functions that call authenticateUser
MATCH (caller:CODE_SYMBOL)-[:CALLS]->(callee:CODE_SYMBOL)
WHERE callee.name = "authenticateUser"
RETURN caller.name, caller.file_path

Example Walkthrough

Finding Authentication Code

1. Get the map:

GET map://my-app

2. Identify auth community:

{
  "id": "comm_auth",
  "label": "Authentication",
  "symbols": 85,
  "cohesion": 0.92,
  "entry_points": ["login", "signup", "refreshToken"]
}

3. Explore the community:

GET map://my-app/community/comm_auth

4. Start with entry point: Find the login function location, open the file, start reading.

5. Trace the login process:

GET map://my-app/process/proc_login

See the full flow: handleLogin → authenticateUser → getUserByEmail → createSession

6. Query for dependencies:

MATCH (s:CODE_SYMBOL {name: "authenticateUser"})-[:CALLS]->(dep:CODE_SYMBOL)
RETURN dep.name, dep.file_path

Tips

For Large Codebases

Start with high-level communities - Don't dive into details immediately
Look for well-named communities - Good names hint at functionality
Follow entry points - They're designed to be starting points
Use processes - They show how code actually executes

Finding Specific Features

Search first - Context search is fast
Filter by community - Results are grouped by community
Check processes - Feature might be a full process
Query relationships - Find how features connect

Understanding Architecture

Study cross-flows - See major dependencies
Check cohesion scores - High scores indicate good design
Trace cross-community processes - Understand system boundaries
Query community membership - See which code belongs where

Common Patterns

Pattern 1: "Where is feature X?"

// 1. Search for it
const search = await contextSearch({
  q: "feature X implementation",
  task_context: "Finding feature X",
  current_goal: "Locate implementation",
  search_intention: "Start reading code"
});

// 2. Check which community it's in
const communityId = search.processes[0].community_id;

// 3. Explore that community
const community = await getResource(`map://my-app/community/${communityId}`);

Pattern 2: "How does Y work?"

// 1. Find the community containing Y
const map = await getResource('map://my-app');
const community = map.communities.find(c => c.key_symbols.includes('Y'));

// 2. Get community details
const details = await getResource(`map://my-app/community/${community.id}`);

// 3. Find processes involving Y
const processes = details.processes.filter(p => p.label.includes('Y'));

// 4. Trace the process
const trace = await getResource(`map://my-app/process/${processes[0].id}`);

Pattern 3: "What calls function Z?"

MATCH (caller:CODE_SYMBOL)-[:CALLS]->(z:CODE_SYMBOL {name: "Z"})
RETURN caller.name, caller.file_path, caller.symbol_type
ORDER BY caller.name

Context Search Tool - Find code quickly
Codebase Map - Start here
Community Detail - Deep dives
Process Trace - Follow execution

Exploring an Unfamiliar Codebase

On this page