Folder Structure

By the end of this lesson, you’ll be able to glance at any project’s folder structure and know where things belong — so you can give precise directions to your AI assistant instead of vague ones.

The Mental Model: A Filing Cabinet

Think of project structure like a filing cabinet in an office. You could throw every document into one drawer and technically find things eventually. But a well-organized cabinet has labeled drawers, tabbed folders, and a consistent system that anyone can follow.

The same principle applies to software projects:

• One drawer for pages (what visitors see)
• One drawer for reusable pieces (headers, buttons, cards)
• One drawer for styles (how things look)
• One drawer for utilities (helper tools)

When you tell an AI “add a new page,” it needs to know which drawer to open. That is your job as the orchestrator.

Why Structure Matters

You could throw all your files into one folder and things would technically work. But as projects grow, organization becomes essential. Good structure means:

• You (and the AI) can find things quickly
• Related files live together
• New files have an obvious home
• The project is understandable at a glance

Here is a concrete comparison. Imagine a project with 20 files:

Disorganized (everything in one folder):

my-project/
├── Header.jsx
├── app.js
├── about.html
├── auth.js
├── button.css
├── contact.html
├── footer.css
├── format.js
├── global.css
├── header.css
├── index.html
├── logo.png
├── main.js
├── nav.css
├── package.json
├── photo1.jpg
├── photo2.jpg
├── sidebar.jsx
├── validate.js
└── README.md

Organized (grouped by purpose):

my-project/
├── src/
│   ├── components/        <- Reusable UI pieces
│   │   ├── Header.jsx
│   │   └── Sidebar.jsx
│   ├── pages/             <- Each page of the site
│   │   ├── index.html
│   │   ├── about.html
│   │   └── contact.html
│   ├── styles/            <- All stylesheets
│   │   ├── global.css
│   │   ├── header.css
│   │   ├── nav.css
│   │   ├── footer.css
│   │   └── button.css
│   ├── scripts/           <- Application logic
│   │   ├── app.js
│   │   ├── main.js
│   │   └── auth.js
│   └── utils/             <- Helper functions
│       ├── format.js
│       └── validate.js
├── public/                <- Static assets
│   ├── logo.png
│   ├── photo1.jpg
│   └── photo2.jpg
├── package.json
└── README.md

Same 20 files. The organized version tells a story at a glance: this is a website with three pages, a couple of reusable components, custom styles, some application logic, and helper utilities. You can direct the AI with confidence: “Add a new page in src/pages/” or “Create a date formatting helper in src/utils/.”

Common Patterns

Pattern 1: Simple Static Site

For basic HTML/CSS/JS websites:

my-site/
├── index.html
├── about.html
├── css/
│   └── style.css
├── js/
│   └── main.js
├── images/
│   └── logo.png
└── README.md

Rule: Group files by type (CSS together, JS together, images together).

Pattern 2: Modern Web App

For projects using a framework (React, Astro, Next.js, etc.):

my-app/
├── src/
│   ├── components/        <- Reusable UI pieces
│   │   ├── Header.jsx
│   │   ├── Footer.jsx
│   │   └── Button.jsx
│   ├── pages/             <- Each page of the app
│   │   ├── index.jsx
│   │   ├── about.jsx
│   │   └── contact.jsx
│   ├── styles/            <- Stylesheets
│   │   └── global.css
│   └── utils/             <- Helper functions
│       └── format.js
├── public/                <- Static assets
│   ├── favicon.ico
│   └── images/
├── package.json
├── README.md
└── .gitignore

Rule: Group files by function (components, pages, styles, utilities). Note: frameworks differ in specifics — for example, Next.js often uses app/ instead of src/pages/, and Astro uses src/pages/. The organizational principle (group by function) is the same.

Pattern 3: API / Backend

For server-side applications:

my-api/
├── src/
│   ├── routes/            <- API endpoints
│   │   ├── users.js
│   │   └── products.js
│   ├── models/            <- Data structures
│   │   ├── user.js
│   │   └── product.js
│   ├── middleware/         <- Request processing
│   │   └── auth.js
│   └── index.js           <- Entry point
├── tests/                 <- Test files
│   ├── users.test.js
│   └── products.test.js
├── package.json
└── .env                   <- Environment variables (secrets)

Rule: Group files by architectural role (routes handle requests, models define data, middleware processes requests in between).

Pattern 4: Python Data Project

For data analysis, research scripts, and CLI tools:

my-analysis/
├── src/
│   ├── __init__.py
│   ├── main.py            <- Entry point
│   ├── loader.py           <- Data loading and cleaning
│   └── visualize.py        <- Chart generation
├── data/
│   ├── raw/                <- Original data (never edit)
│   └── processed/          <- Cleaned output
├── output/                 <- Generated reports, charts
├── tests/
│   └── test_loader.py
├── requirements.txt
└── README.md

Rule: Separate raw data from processed data and output. Source code in src/, never edit files in data/raw/.

You may also encounter domain-specific structures outside web apps. Here are two examples from other fields:

gene-expression-analysis/
├── data/
│   ├── raw/               <- Original FASTQ/CSV files (never edit)
│   ├── processed/         <- Cleaned, normalized data
│   └── reference/         <- Genome references, annotations
├── scripts/
│   ├── 01-preprocess.py
│   ├── 02-align.py
│   └── 03-analyze.py
├── results/
│   ├── figures/
│   └── tables/
├── docs/
│   └── methods.md
└── README.md

sales-dashboard/
├── src/
│   ├── components/
│   │   ├── RevenueChart.jsx
│   │   ├── KPICard.jsx
│   │   └── FilterBar.jsx
│   ├── pages/
│   │   ├── overview.jsx
│   │   └── regional.jsx
│   └── utils/
│       └── formatCurrency.js
├── data/
│   ├── sales-2024.csv
│   └── regions.json
└── package.json

Key Naming Conventions

The src/ Convention

Many modern projects use a src/ folder (though not all — some frameworks use app/ or keep files at the root). src/ stands for “source” — it contains the code you write (or that the AI writes for you). Outside src/ you will often find configuration, static assets, tests, scripts, and dependency/build folders.

project/
├── src/          <- YOUR code lives here
├── node_modules/ <- Downloaded dependencies (don't touch)
├── dist/         <- Build output (generated, don't touch)
├── package.json  <- Configuration
└── README.md     <- Documentation

The simple rule: When in doubt, put it in src/.

This is like the “working area” of a lab bench. The src/ folder is where the active work happens. Everything else is either supplies (node_modules), output (dist), or labels (package.json, README.md).

Worked Example: Directing the AI with Structure

Let’s say an AI created this project for you:

campus-events/
├── src/
│   ├── components/
│   │   ├── EventCard.jsx
│   │   ├── Header.jsx
│   │   └── SearchBar.jsx
│   ├── pages/
│   │   ├── index.jsx         <- Homepage
│   │   └── event/[id].jsx   <- Individual event pages (brackets = dynamic route)
│   ├── styles/
│   │   └── global.css
│   └── utils/
│       └── formatDate.js
├── public/
│   └── images/
├── package.json
└── README.md

Now your stakeholder asks for four new features. Here is how you would direct the AI for each one:

You do not need to know how to code these features. You need to know where they belong so the AI puts them in the right place.

What AI Tools Generate

When you tell Claude Code or Gemini CLI to “create a React app,” the tool will generate a standard project structure automatically. It follows the conventions of whatever framework it is using.

Your role as an orchestrator:

1. Understand what the folders mean (not every file, just the pattern)
2. Direct the AI to the right location: “Add a new component in src/components/”
3. Verify things are in logical places
4. Reorganize if something feels off: “Move the utility functions to src/utils/“

When Things Go Wrong

Building Your Intuition

You do not need to memorize folder structures. You need to develop an intuition for where things belong. Here is how:

1. When an AI creates a project, look at the structure and understand the top-level folders
2. When you need to add something, think: “Is this a component, a page, a style, or a utility?” and direct the AI to the right folder
3. When something feels disorganized, ask the AI: “Reorganize this project to follow standard conventions”

Quick commands for exploring structure:

# See top-level structure
ls

# See recursive structure (if tree is installed)
tree -L 2

# Create standard folders for a new project
mkdir -p src/{components,pages,styles,utils} public/images

# Move a misplaced file
mv src/pages/DataTable.jsx src/components/DataTable.jsx

Over time, this becomes second nature. You will glance at a project structure and immediately understand where everything is and where new things should go.

Key Takeaways

• Structure = communication. A well-organized project tells you (and the AI) where everything belongs at a glance
• Three common patterns: static sites group by file type, web apps group by function, APIs group by architectural role
• The src/ folder is where your code lives — everything else is configuration, dependencies, or output
• Your orchestrator job is to read the structure and direct the AI to the right location: “Put this component in src/components/”
• When the AI makes a mess, ask it to reorganize — you do not need to move files manually