> ## 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.
# Multi file Project Navigation
> Explains using Claude Code to inspect, navigate, and modify multi-file projects, summarize file relationships, and plan safe changes such as database migrations.
This lesson explains how to work with multiple files in a project, navigate a codebase, and use Claude Code to analyze or modify an entire repository rather than a single file. You’ll see how Claude inspects the repository structure, summarizes how files relate, and recommends targeted changes (for example, for a database migration).
## Inspecting a repository
Claude can list the repository contents and return a concise file tree so you can quickly understand the app layout:
```text theme={null}
cwd: /Users/jeremy/Repos/Claude Code Course/Express-login-demo
> 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
```
From the tree, Claude can produce a clear summary of the main components and how they connect:
```text theme={null}
Summary of main components:
– server.js – Main Express application entry point
– config/database.js – PostgreSQL database connection pool
– routes/auth.js – Authentication routes (currently only login)
– schema.sql – Database schema definition
Route-Controller Architecture:
– Routes are mounted using Express Router patterns:
• server.js mounts auth routes at /api/auth (e.g., server.js:11)
• routes/auth.js handles the /login endpoint (inline controller logic)
– No separate controller layer — business logic is embedded in route handlers
Database:
– PostgreSQL (pg) with a connection pool (config/database.js)
– Single users table: id, email, name, password, timestamps (schema.sql)
– Email index for performance
– Uses bcrypt for password hashing and JWT for authentication tokens
```
Because Claude analyzes multiple files together, you can ask higher-level questions such as “What files would be affected if we change the database to MariaDB?” and get a focused list of files and specific edits.
## Example: Files affected by a database migration
Here’s an example list of files and the typical changes required when migrating from PostgreSQL to MariaDB/MySQL:
| File / Area | Change required | Quick example |
| - | - | - |
| `package.json` | Replace Postgres client with a MySQL/MariaDB client | Replace `pg` with `mysql2` or `mariadb` |
| `config/database.js` | Re-implement the connection pool API and connection options | Use `mysql2.createPool(...)` instead of `new Pool(...)` |
| `routes/auth.js` | Update parameterized query placeholders and query execution | PostgreSQL uses `$1`, MySQL often uses `?` or named placeholders |
| `schema.sql` | Convert Postgres-specific DDL to MySQL syntax | `SERIAL` -> `AUTO_INCREMENT`; check timestamp defaults |
| `.env` / env vars | Update DB port, connection parameters | MySQL default port `3306` vs Postgres `5432` |
Notes:
* Using parameterized queries and a query builder/ORM improves portability.
* Placeholder syntax and pool configuration are the main code-level differences.
## Example file: current PostgreSQL pool (before migration)
This is an example `config/database.js` using the `pg` client:
```javascript theme={null}
const { Pool } = require('pg');
const pool = new Pool({
host: process.env.DB_HOST,
port: process.env.DB_PORT,
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;
```
To migrate to a MySQL driver like `mysql2`, you’d replace the `pg` Pool implementation with `mysql2`’s pool API and update query parameter placeholders and execution calls.
## How Claude performs multi-file edits safely
Claude supports file-level operations and constraints. Examples of common workflows:
* Inspect: Ask Claude to summarize the project structure and identify key components to target.
* Plan: Request a list of files and specific changes required for a migration or refactor.
* Restrict: Specify which files may be changed and which must remain unchanged.
* Apply & Verify: Have Claude perform the changes and then verify that the specified files were refactored.
You can also instruct Claude to avoid modifying certain files; if a requested change requires touching excluded files, Claude will flag the conflict and request permission.
When requesting modifications, specify the files that may be changed and which files must not be modified. This avoids accidental edits to unrelated parts of the codebase.
## Practical dos and don'ts for multi-file work with Claude
* Do provide contextual groupings (for example, “the auth system consists of these three files”) instead of pasting every file.
* Do ask Claude to analyze relationships between files (routes → controllers → database) before making large changes.
* Don’t paste a massive, unrelated list of files without context; Claude already knows the repo structure and will reprocess unnecessarily.
* Don’t copy code from an unrelated stack (for example, React components) and expect it to work unmodified in a Node/Express application.
## Why multi-file awareness matters
Multi-file analysis is especially valuable for:
* Refactors where business logic moves between layers (routes → controllers → services).
* Migrations (databases, auth providers) that touch configuration, schema, and queries.
* Understanding legacy codebases where relationships span several files.
Claude’s ability to reason across files reduces the manual work of tracing dependencies and speeds up safe, targeted edits.
## Links and references
* [Express - Node.js web framework](https://expressjs.com/)
* [PostgreSQL Documentation](https://www.postgresql.org/docs/)
* [mysql2 on npm](https://www.npmjs.com/package/mysql2)
* [MariaDB Documentation](https://mariadb.com/kb/en/documentation/)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.