Project Structure for AI Coders | SheCodes
Beginner 5 min read

Project Structure for AI Coders

Your project is like a house. Every file and folder has a purpose, just like rooms and furniture. Here is what each part does, in plain English.

In this chapter

  • What every folder in an AI-generated project is for
  • How to find the file you need to change
  • Why some files belong in public/ and others in app/
  • How to ask AI to reorganize messy projects

Your Project is a House

Every project has a few main folders. Think of them as different parts of your house.

app/ The rooms in your house. Each folder inside here becomes a page on your website. A folder called "about" becomes your /about page. A folder called "blog" becomes your /blog page. Analogy: Adding a new folder in app/ is like adding a new room to your house. Each room has its own address that visitors can walk to.
components/ The furniture you can move between rooms. A navigation bar, a footer, a button, a card: these are pieces you build once and reuse on multiple pages. Analogy: A couch can go in the living room or the den. A component can go on your homepage or your about page.
public/ Your front yard: anyone can see it. This is where you put images, your site icon (favicon), and any files you want visitors to access directly. Analogy: Your front yard decorations are visible to everyone walking by, no key needed. Same with files in public/.

Other Important Folders

You will see a few more folders in your project. Here is what they are for.

lib/ Your toolbox. Helper functions and settings that your pages and components share. Think of it like a utility drawer in the kitchen (scissors, tape, screwdriver): stuff everything uses but nobody sees.
api/ (inside app/) The back office. This is where behind-the-scenes work happens, like saving data, sending emails, or talking to other services. Visitors never see this, but it powers things that happen when they click buttons.
node_modules/ Stuff other people built for you. When your AI tool adds a feature that needs an outside package, it goes here. You never need to touch this folder. It manages itself.
.env.local Your secret diary. Passwords, API keys, and private settings live here. Never share this file. Never post it online. Your AI tool knows to keep it private.

Special Files You Will See

Inside each folder, some filenames have special meanings. Your AI tool creates these for you, but it helps to know what they do.

page

This is the content of a page. Every folder in app/ that has one of these becomes a real page on your website.

The interior design of a room: what visitors actually see when they walk in.

layout

The shared wrapper around your pages. Your navigation bar and footer usually live here so they appear on every page.

The walls, ceiling, and floor that every room shares.

loading

What visitors see while a page is still loading. A spinner, a progress bar, or a nice animation.

A 'Please wait' sign on a door while the room is being prepared.

error

What visitors see if something goes wrong on a page. A friendly message instead of a scary crash.

An 'Oops, something broke' note taped to the door.

not-found

What visitors see when they type a URL that does not exist. Your custom 404 page.

A sign that says 'This room does not exist' when someone wanders to the wrong address.

globals.css

The overall look and feel of your entire site (colors, fonts, spacing). Shared by all pages.

The paint colors and flooring style you chose for the whole house.

How Files Get Their Names

You do not need to memorize these rules. Your AI tool handles naming for you. But knowing the patterns helps you understand what is going on.

Pages and folders

Use lowercase with dashes between words.

A page about your pricing plans would live in a folder called pricing-plans, not "PricingPlans" or "pricing_plans". Dashes are the standard because they work well in website addresses.

Components (reusable pieces)

Use capitalized words pushed together.

A navigation bar component would be called Navbar. A sign-up form would be SignUpForm. This capitalization tells your project "this is a building block I can reuse."

Settings and secrets

Use ALL CAPS with underscores.

Secret values like your database password or API key use names like DATABASE_URL or API_KEY. The caps make them stand out as important settings you should not change casually.

Square brackets in folder names

Like [slug]: this means "a page that changes."

If you have a blog, you do not make a separate folder for every post. Instead, a folder called [slug] automatically creates a page for each one. Think of it as a template room that transforms based on who walks in.

What to Tell Your AI Tool

Instead of writing any of this yourself, just tell your AI tool what you want. Here are prompts you can copy and paste.

Add a new page to your site

“Create a new page at /pricing that shows three pricing tiers in cards. Add it to the navigation bar too.”

Create a reusable component

“Make a reusable testimonial card component that I can use on both the homepage and the about page. It should show a quote, person's name, and their photo.”

Add an image to your site

“I have a logo image. Where should I put it in my project so I can use it on my website? Add it to the navigation bar.”

Understand your project structure

“Explain what each file and folder in my project does. I am a beginner and do not know how to read code.”

Set up a secret key or password

“I need to add my Stripe API key to this project. Set it up securely so it is not visible to website visitors and not shared publicly on GitHub.”

How to Ask Your AI Tool to Reorganize Files

As your project grows, it might get messy. That is totally normal. Here is how to ask your AI tool to tidy things up.

Your components folder is getting crowded

“I have too many files in my components folder. Can you organize them into subfolders by category, like layout, forms, and shared UI pieces? Update all the imports too.”

You want to rename a page

“Rename my /services page to /what-we-do. Make sure all links and navigation still work after the rename.”

You are not sure what is safe to delete

“Are there any unused files or components in my project that I can safely delete? Show me what each one is before removing anything.”

Your project needs a shared utility

“I keep repeating the same date formatting logic on different pages. Can you move it into a shared helper in the lib folder and update everywhere it is used?”

Frequently Asked Questions

Do I need to create these folders myself?

No. When you start a new project with a tool like Claude Code, Cursor, or Bolt, it creates all the folders for you. You just describe what you want to build.

What happens if I put a file in the wrong folder?

Nothing will explode, but things might not work as expected. For example, if you put an image in app/ instead of public/, your site will not be able to show it. If something is not working, ask your AI tool: "I added a file but it is not showing up. Can you check if it is in the right place?"

Can I rename folders to whatever I want?

Some folders have special names that your project depends on, like app/, public/, and components/. You can rename the folders inside app/ (those become your page URLs), but do not rename the main ones unless your AI tool says it is safe.

What is the src/ folder I keep seeing?

It stands for "source". It is just a container that holds your app/, components/, and lib/ folders. Think of it as the property line around your house. Everything inside it is your project's actual work.

My project looks different from what is shown here. Is that okay?

Yes. Different AI tools and project templates set things up slightly differently. The core ideas are the same: pages go in one place, reusable pieces go in another, and public files are accessible to everyone. Ask your AI tool to explain your specific setup.

How do I add a new page to my website?

Just ask your AI tool. Say something like: "Add a new page called /contact with a contact form." It will create the right folder and files for you in the app/ directory.