> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Demo Multi file Project Navigation
> Guide to using Claude Code for navigating multi-file projects, summarizing structure, proposing and verifying cross-file refactors such as database migrations.
In this lesson you'll learn how to navigate multi-file projects, inspect project structure, and perform cross-file analysis and refactors with Claude Code. We'll cover how Claude Code reads the working directory, summarizes relationships between files, proposes changes (for example, a DB migration), and verifies refactors across multiple files.
## What Claude Code provides for multi-file projects
Claude Code can:
* Inspect the current working directory and list files and folders.
* Produce a project-level summary (entry points, route structure, DB layer, where business logic lives).
* Identify which files need changing for a cross-file task (for example, migrating a database driver).
* Execute or propose targeted refactors while respecting file-level constraints.
* Verify that intended changes were applied to the correct files.
## Launching Claude Code from a project directory
Example of starting Claude Code in a local repo:
```bash theme={null}
jeremy@MACSTUDIO Express-login-demo % claude
* Welcome to Claude Code!
/help for help, /status for your current setup
cwd: /Users/jeremy/Repos/Claude Code Course/Express-login-demo
> Try "create a small logging.py that..."
? for shortcuts
```
## Show the file structure
Ask Claude Code to show the repository layout. Example output:
```bash theme={null}
> show me the file structure of this application
• List(~/Repos/Claude Code Course/Express-login-demo)
└ Listed 12 paths (ctrl+r to expand)
• Express-login-demo/
├── config/
│ └ database.js
├── examples.md
├── node_modules/
├── package.json
├── package-lock.json
├── routes/
│ └ auth.js
├── schema.sql
└ server.js
>
? for shortcuts
```
## Project-level summary (condensed)
Claude Code can turn a file listing into an actionable summary. The following table captures the information from the example project:
| Path | Role / Purpose | Notes |
| ------------------ | ------------------------ | ---------------------------------------------------- |
| server.js | Main Express entry point | Mounts routers and configures middleware |
| config/database.js | DB connection pool | Uses pg for PostgreSQL pooling |
| routes/auth.js | Authentication routes | Contains /login endpoint and inline controller logic |
| schema.sql | Database schema | Users table, indexes, and timestamps |
High-level architecture:
* Route-controller pattern: server.js mounts auth routes at /api/auth; auth router contains inline controllers (no separate controller layer).
* Database: PostgreSQL with the pg client, connection pooling, bcrypt for password hashing, and JWT for tokens.
Claude Code can answer follow-up questions like:
* How are routes connected to controllers?
* What database driver and pooling strategy are in use?
## Example workflow: migrating PostgreSQL → MariaDB
When planning a migration (for example PostgreSQL → MariaDB), Claude Code lists affected files and the exact types of changes required.
Files likely to need direct modification:
| File | Change Required |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| package.json | Replace `pg` with `mysql2` or `mariadb` dependency |
| config/database.js | Reimplement connection pooling using the chosen MariaDB client |
| routes/auth.js | Update parameter placeholder syntax (Postgres `$1` → `?`) and any client-specific query handling |
| schema.sql | Convert Postgres-specific SQL to MariaDB/MySQL equivalents |
Schema-level adjustments to review:
* SERIAL PRIMARY KEY → AUTO\_INCREMENT PRIMARY KEY
* Remove or replace `\c` database commands (use `USE dbname` or omit)
* Review timestamp defaults, UUID usage, and any Postgres-specific data types
Environment updates:
* .env: change default port (MariaDB usually 3306 vs Postgres 5432) and driver-specific connection variables.
Example text output Claude Code might produce when identifying required changes:
```text theme={null}
Based on the codebase analysis, these files would need changes for MariaDB migration:
Direct changes required:
- package.json: replace pg dependency with mysql2 or mariadb
- config/database.js: rewrite to use MariaDB client and connection pooling
- routes/auth.js: update parameter placeholder syntax ($1 -> ?) and any client-specific query code
Schema changes:
- schema.sql: convert PostgreSQL-specific syntax
- SERIAL PRIMARY KEY -> AUTO_INCREMENT PRIMARY KEY
- \c database commands -> USE statement (or remove if not needed)
- adjust defaults and data type specifics if required (timestamps, uuid usage, etc.)
Environment variables:
- .env: update connection parameters (default port 3306 for MariaDB vs 5432 for Postgres)
```
## Existing PostgreSQL connection pool (example)
Here is the typical pattern you might find in config/database.js when using Postgres. This is the code you would replace when migrating to MariaDB:
```javascript theme={null}
const { Pool } = require('pg');
const pool = new Pool({
host: process.env.DB_HOST,
port: Number(process.env.DB_PORT) || 5432,
database: process.env.DB_NAME,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
});
pool.on('connect', () => {
console.log('Connected to PostgreSQL database');
});
module.exports = pool;
```
Note: When migrating, swap this implementation for a MariaDB client (for example, mysql2 or mariadb) and adapt pooling and query methods accordingly.
Parameterized queries separate values from SQL, improving safety. Placeholder syntax differs between drivers — Postgres uses $1, $2, ...; many MySQL/MariaDB clients use `?` or named placeholders. Update your query placeholders and any client-specific methods when switching drivers.
## File-level instructions and safety controls
Claude Code accepts precise file-level instructions:
* Tell it exactly which files it may modify (e.g., only auth-related files).
* Or explicitly list files that must not be changed; Claude will warn if a requested modification would require touching those files.
Best practices:
* Provide contextual information about how files relate (for example: “server.js mounts the routers; auth logic lives in routes/auth.js”).
* Limit the list of files you paste — Claude Code already knows the repository layout and can focus on the relevant files.
## Verifying refactors
After a refactor, ask Claude Code to:
* Confirm which files were modified.
* Show diffs or summarize the applied changes.
* Run static checks (lint/test) or provide commands to run tests locally.
## Do's and don'ts
| Do | Don't |
| ----------------------------------------------- | --------------------------------------------------------------- |
| Provide relationships between files for context | Paste huge unstructured file lists and expect manual sorting |
| Specify which files can or cannot be modified | Mix incompatible contexts without clear adaptation instructions |
| Ask for verification after changes | Assume a large refactor is safe without testing or review |
## Summary
Claude Code helps you navigate multi-file projects by:
* Mapping file structure and relationships,
* Summarizing architecture and responsibilities,
* Proposing and implementing targeted cross-file refactors (like DB migrations),
* Respecting file-level constraints, and
* Verifying the results.
This workflow accelerates working with legacy codebases, multi-file apps, and incremental migrations while reducing human error.
## Links and references
* [PostgreSQL Documentation](https://www.postgresql.org/docs/)
* [MariaDB Documentation](https://mariadb.com/kb/en/documentation/)
* [node-postgres (pg) npm package](https://www.npmjs.com/package/pg)
* [mysql2 npm package](https://www.npmjs.com/package/mysql2)