How to read a project's folder structure without getting lost

Start at the Top

When you open an unfamiliar repo, your first instinct is to grep for something recognizable. Resist that. Start at the root and read the directory names as a table of contents.

Common patterns you'll see across projects:

• src/ — application source code
• lib/ — shared utilities or compiled output
• dist/ or build/ — generated files, never edit these
• config/ or .config files — environment and tool setup
• test/ or __tests__/ — test suites, great for understanding intent

Find the Entry Point First

Every project has an entry point — the file execution starts from. For Node.js, check package.json → main or scripts.start. For Python, look for main.py or __main__.py. For web apps, check index.html or index.js.

// package.json entry point clues
{
  "main": "src/index.js",       // library entry
  "scripts": {
    "start": "node src/server.js" // app entry
  }
}

Read the README Like a User

The README tells you what the project claims to do. Run the quickstart locally before reading a single line of source. Seeing it work gives your brain a mental model that makes the code readable — without it, you're decoding symbols with no context.