Folder Structure

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

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).

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)

Key naming conventions

Convention	Example	When to use
`kebab-case`	`my-component.jsx`	File names (most common)
`PascalCase`	`MyComponent.jsx`	React component files
`camelCase`	`formatDate.js`	Utility function files
Plural folders	`components/`, `pages/`, `utils/`	Always for folders containing multiples
`src/`	Source folder	Almost every modern project

💡Don't overthink this

Structure conventions are just conventions — the code works regardless. When an AI tool scaffolds a project, it follows standard conventions automatically. Your job is to understand the structure enough to give good instructions, like “put this in the components folder” or “create a new page in the pages directory.”

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’s using.

Your role as an orchestrator:

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

The `src/` convention

Almost every modern project uses a src/ folder. This stands for “source” — it contains the code you write (or that the AI writes for you). Everything outside src/ is typically configuration, dependencies, or build output.

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/.

Building your intuition

You don’t need to memorize folder structures. You need to develop an intuition for where things belong. Here’s how:

When an AI creates a project, look at the structure with ls and understand the top-level folders
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
When something feels disorganized, ask the AI: “Reorganize this project to follow standard conventions”

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