Lab 1.2: Codebase Exploration

Module: 1.2 - Codebase Exploration | ← SlidesDuration: 1 hour Sample Project: node-express-mongoose-demo

Learning Objectives

By the end of this lab, you will be able to:

• Navigate an unfamiliar codebase using Claude Code
• Ask progressively deeper questions (broad → narrow)
• Trace execution flows across multiple files
• Identify key data models and their relationships

Prerequisites

• Claude Code installed and working
• Sample projects cloned (run sample-projects/setup.sh)
• MongoDB running (via Docker or locally)

Setup

# Navigate to the sample project
cd sample-projects/node-express-mongoose-demo

# Install dependencies
npm install

# Start Claude Code
claude

---

Task 1: Find the Entry Points

Time: 10-12 minutes

Ask Claude to identify how the application starts.

Prompts to try:

What are the main entry points of this application?

Show me the code for the primary entry point.

Expected Outcome

You should know which file(s) start the application and why.

Success criteria:

• [ ] Identified the main server file
• [ ] Understand what happens when the app starts

---

Task 2: Trace an Execution Flow

Time: 15-20 minutes

Pick a core feature and trace it end-to-end.

Prompts to try:

Walk me through the user login process, step by step.

Trace the execution flow when a user creates a new article.

What happens when a user submits the registration form?

Expected Outcome

Understand the complete flow from user action to database.

Success criteria:

• [ ] Traced a complete flow (route → controller → model → database)
• [ ] Can explain the flow to someone else

---

Task 3: Clarify Specific Modules

Time: 10-15 minutes

Find confusing code and ask Claude to explain it.

Prompts to try:

What does the middleware in `config/express.js` do?

Why does this application use Mongoose?

What is the purpose of the `lib/` directory?

Expected Outcome

Understand the intent behind the code, not just what it does.

Success criteria:

• [ ] Identified at least 3 modules/files and their purposes
• [ ] Understand why certain architectural decisions were made

---

Task 4: Identify Data Models

Time: 10-15 minutes

Map out the core entities in the application.

Prompts to try:

What are the key data models in this application?

How is the Article model structured?

Where is the User model created, read, updated, and deleted?

Expected Outcome

Know the core entities and how they flow through the system.

Success criteria:

• [ ] Listed all major data models
• [ ] Understand the relationships between models
• [ ] Know where CRUD operations happen for at least one model

---

Tips for Success

Do	Don't
Start broad, then narrow	Jump into details immediately
Be specific about scope	Ask vague questions like "explain the code"
Ask why, not just what	Accept surface-level answers
Request examples	Assume you understand without verification

Example progression:

"What does this app do?"
  → "How does auth work?"
    → "Explain the hashPassword function"

---

Troubleshooting

Claude gives vague answers

• Try rephrasing with more specific scope
• Reference a specific file or line number

Claude seems confused

• Break your question into smaller parts
• Provide context: "I'm looking at the auth flow..."

Claude makes a mistake

• Verify by reading the actual code
• Ask Claude to show you the specific code it's referencing

---

Stretch Goals

If you finish early:

1. Create an EXPLORATION_NOTES.md file documenting your findings
2. Draw a diagram of the main execution flows
3. Identify potential code smells or improvement areas

---

Deliverables

At the end of this lab, you should have:

1. A mental model of the application structure
2. Notes on key entry points, flows, and data models
3. Questions to share during the debrief

---

Next Steps

After completing this lab, move on to Lab 1.3: Building the Project Brain.