1.3 File Structures & Why They Matter

Time: ~25 minutes

What You'll Learn

• Why file structure matters more than you think
• Common patterns in modern web projects
• Why AI loves to create spaghetti and how to stop it
• How to recognize a healthy vs messy project

The Spaghetti Problem

Here's what happens to most vibe-coded projects:

1. You ask AI to build a feature. It creates some files.
2. You ask for another feature. More files appear.
3. You ask for a fix. AI creates a new file instead of editing the right one.
4. Repeat 20 times.

Now you have 47 files, half of them are duplicates, and nobody (including the AI) knows which ones are actually being used.

This is the spaghetti problem. And it kills projects.

What a Healthy Project Looks Like

Most modern web projects follow a predictable structure:

my-project/
  src/
    components/     -- Reusable UI pieces
    pages/          -- Each page of your app
    styles/         -- CSS files
    utils/          -- Helper functions
    lib/            -- API calls, database connections
  public/           -- Images, fonts, static files
  package.json      -- Project dependencies
  next.config.js    -- Configuration

The specifics vary by framework, but the principle is universal: related things live together, different things live apart.

Key Directories Explained

src/components/

Reusable pieces of your UI. A button, a navigation bar, a card layout. If you use it in more than one place, it goes here.

src/pages/ (or app/)

Each file in this directory typically becomes a URL on your site. pages/about.tsx becomes yoursite.com/about.

src/lib/ or src/utils/

Helper code that isn't visual. API calls, data formatting, authentication logic.

public/

Static files that don't need processing -- images, fonts, favicons.

package.json

The most important file you never write yourself. It lists every library your project depends on.

Why AI Creates Spaghetti

AI coding tools create messy file structures because:

1. No memory across sessions -- Each conversation starts fresh, so AI doesn't remember what files exist
2. Path of least resistance -- Creating a new file is easier than finding and editing the right one
3. No project awareness -- Unless you tell it, AI doesn't know your project's conventions
4. Duplication over modification -- AI would rather write a new utility function than find the existing one

How to Prevent It

Three habits that keep projects clean:

1. Start with structure

Before you write any code, establish your directory structure. Even if it's mostly empty folders. AI respects existing structure much better than it creates new structure.

2. Reference existing files

When asking for changes, point to the files that already exist:

"Edit the Header component in src/components/Header.tsx to add a search bar"

Not:

"Add a search bar to the header"

3. Audit regularly

Every few features, ask your AI: "Look at my project structure. Are there any duplicate files or things in the wrong place?"

Recognizing a Healthy Project

Signs your project is well-organized:

• You can find any file in under 10 seconds
• Each file has one clear purpose
• Related files are in the same directory
• There are no mystery files you're afraid to delete

Signs your project needs cleanup:

• Files named utils2.js or Header-old.tsx
• The same function defined in multiple places
• You're not sure which files are actually used
• Your AI keeps creating new files instead of editing existing ones

Practice

Look at a project you're currently working on (or have worked on) and answer:

1. Can you explain what each top-level directory contains?
2. Are there any files you're not sure about?
3. Is there any duplication?

If you don't have a project yet, create an empty directory structure for a simple web app using the pattern above.

Key Takeaways

• File structure is the difference between a project that scales and one that collapses
• AI tools create spaghetti by default -- you need to guide them
• Start with structure, reference existing files, and audit regularly
• A well-organized project is one where you can find anything in 10 seconds

Next Up

Your project is organized. But something broke. Time to learn the most valuable skill in all of programming: reading error messages.

Continue to 1.4 Reading Error Messages