Understand a Codebase¶

Time: 15 minutes | Tools: get_project_map, crawl_project | Tier: Community/Pro

Learn how to quickly orient yourself in an unfamiliar codebase.

What You'll Learn¶

• Map entire project structure
• Identify entry points
• Find complexity hotspots
• Detect potential issues

The Scenario¶

You've just joined a team and need to understand their Flask application. Instead of reading every file, use Code Scalpel to get the big picture fast.

Step 1: Get the Project Map¶

"Give me an overview of this project"

Tool call:

{
  "tool": "get_project_map",
  "parameters": {
    "project_root": "./flask_app",
    "include_complexity": true,
    "complexity_threshold": 10
  }
}

Result:

{
  "data": {
    "project_root": "./flask_app",
    "packages": [
      {
        "name": "routes",
        "modules": ["__init__", "auth", "users"],
        "functions": 12,
        "classes": 0
      },
      {
        "name": "services",
        "modules": ["__init__", "user_service", "db_service"],
        "functions": 18,
        "classes": 2
      },
      {
        "name": "models",
        "modules": ["__init__", "user"],
        "functions": 4,
        "classes": 1
      },
      {
        "name": "utils",
        "modules": ["__init__", "validators"],
        "functions": 8,
        "classes": 0
      }
    ],
    "entry_points": [
      {
        "type": "flask_app",
        "file": "app.py",
        "line": 5
      },
      {
        "type": "route",
        "file": "routes/auth.py",
        "function": "login",
        "line": 12
      },
      {
        "type": "route",
        "file": "routes/auth.py",
        "function": "register",
        "line": 28
      },
      {
        "type": "route",
        "file": "routes/users.py",
        "function": "get_users",
        "line": 8
      }
    ],
    "complexity_hotspots": [
      {
        "file": "services/user_service.py",
        "function": "process_user_data",
        "complexity": 15,
        "line": 45
      },
      {
        "file": "routes/auth.py",
        "function": "login",
        "complexity": 12,
        "line": 12
      }
    ],
    "total_files": 9,
    "total_functions": 42,
    "total_classes": 3
  },
  "tier_applied": "pro",
  "duration_ms": 234
}

Step 2: Visualize the Structure¶

The project map includes a Mermaid diagram:

graph TD
    subgraph flask_app
        A[app.py] --> B[routes/]
        A --> C[services/]

        subgraph routes/
            B1[auth.py]
            B2[users.py]
        end

        subgraph services/
            C1[user_service.py]
            C2[db_service.py]
        end

        B1 --> C1
        B2 --> C1
        C1 --> C2
    end

Step 3: Focus on Entry Points¶

Entry points are where execution begins:

These are the places users interact with the system.

Step 4: Investigate Hotspots¶

Complexity hotspots need attention:

"Analyze the process_user_data function in user_service.py"

{
  "tool": "analyze_code",
  "parameters": {
    "file_path": "flask_app/services/user_service.py"
  }
}

High complexity (15) suggests this function: - Has many branches/conditions - May be hard to test - Could be a refactoring candidate

Step 5: Crawl for More Detail¶

For deeper analysis:

"Crawl the entire project and find all issues"

{
  "tool": "crawl_project",
  "parameters": {
    "root_path": "./flask_app",
    "complexity_threshold": 10,
    "include_report": true
  }
}

Crawl provides: - All functions with complexity scores - All imports (internal and external) - All classes and their methods - Potential circular imports - Security warning patterns

Understanding the Results¶

Project Structure¶

Data Flow¶

HTTP Request → routes/ → services/ → models/
                                  ↓
                              db_service

Risk Areas¶

1. High complexity functions - Hard to maintain
2. Entry points - Attack surface
3. Database operations - SQL injection risk
4. User input handling - Validation needed

Try It Yourself¶

Exercise 1: Map Your Own Project¶

"Map the structure of [your project directory]"

Exercise 2: Find Hotspots¶

"Show me the most complex functions in my codebase"

Exercise 3: List Entry Points¶

"What are all the entry points in this project?"

Community vs Pro¶

Key Takeaways¶

1. get_project_map gives you the big picture fast
2. Entry points show where users interact with code
3. Complexity hotspots identify maintenance risks
4. crawl_project provides deep analysis
5. Start high-level, then dive into specifics

Next Tutorial¶

Now that you understand the structure, continue with Cross-File Security Scanning to trace risks across modules.