2.3 Project Structure

Time: ~25 minutes

What You'll Learn

• Why structure matters more as projects grow
• The rules AI follows (and breaks) with file organization
• How to establish conventions AI will respect
• A practical structure guide for common project types

The Growth Problem

In lesson 1.3, we talked about why AI creates spaghetti. Now let's talk about what to do about it as your project scales from 5 files to 50 to 500.

Small projects survive bad structure. You can keep everything in your head. But the moment your project grows beyond what you can remember, structure becomes the difference between progress and paralysis.

Establishing Conventions

The single most effective thing you can do is establish conventions before you start coding and communicate them to AI every time.

Naming Conventions

Pick a pattern and stick with it:

Components:   PascalCase  -> UserProfile.tsx
Utilities:    camelCase   -> formatDate.ts
Styles:       kebab-case  -> user-profile.css
Constants:    UPPER_CASE  -> API_BASE_URL
Directories:  kebab-case  -> user-profile/

File Organization Rules

Decide where things go:

New component? -> src/components/
New page?      -> src/pages/ or src/app/
New API call?  -> src/lib/api/
New utility?   -> src/utils/
New type?      -> src/types/
New hook?      -> src/hooks/

The Convention Document

Create a file in your project root (call it CONVENTIONS.md or ARCHITECTURE.md) that documents your decisions. When you start a new AI session, reference it:

Follow the conventions in CONVENTIONS.md for file naming and placement.

Structure by Project Type

Simple Marketing Site

my-site/
  src/
    components/
      Header.tsx
      Footer.tsx
      Hero.tsx
      ContactForm.tsx
    pages/
      index.tsx
      about.tsx
      contact.tsx
    styles/
      globals.css
  public/
    images/
  package.json

Web App with Authentication

my-app/
  src/
    app/                    -- Pages and routes
      (auth)/               -- Auth-required routes
        dashboard/
        settings/
      (public)/             -- Public routes
        login/
        signup/
      layout.tsx
    components/
      ui/                   -- Generic UI components
        Button.tsx
        Input.tsx
        Modal.tsx
      features/             -- Feature-specific components
        auth/
          LoginForm.tsx
          SignupForm.tsx
        dashboard/
          StatsCard.tsx
          RecentActivity.tsx
    lib/
      api.ts                -- API client setup
      auth.ts               -- Authentication logic
      db.ts                 -- Database connection
    hooks/
      useAuth.ts
      useForm.ts
    types/
      user.ts
      api.ts
    utils/
      formatDate.ts
      validation.ts
  public/
  package.json

API-Heavy Application

my-api-app/
  src/
    components/
    pages/
    lib/
      api/
        users.ts            -- User-related API calls
        products.ts         -- Product-related API calls
        orders.ts           -- Order-related API calls
        client.ts           -- Shared API client config
    types/
      api/
        users.ts            -- User API response types
        products.ts         -- Product API response types
    hooks/
      useUsers.ts           -- Data fetching hook for users
      useProducts.ts        -- Data fetching hook for products

The Colocation Principle

Keep related things close together. If a component has its own styles, types, and tests, put them together:

src/components/UserProfile/
  UserProfile.tsx            -- The component
  UserProfile.test.tsx       -- Tests
  UserProfile.module.css     -- Styles
  index.ts                   -- Re-export for clean imports

This is better than having styles in one directory, tests in another, and components in a third. When you delete a feature, you delete one folder.

Keeping AI in Line

Start each session with context

I'm working on [project name]. Here's the directory structure: [paste tree]. Follow existing patterns for naming and file placement.

Be explicit about file paths

Create a new OrderSummary component at src/components/features/checkout/OrderSummary.tsx

Reject misplaced files

You put the API function in the component file. Move it to src/lib/api/orders.ts and import it from there.

Periodic cleanup prompts

Every few sessions, ask:

Review my project structure. Are there any files that seem misplaced, duplicated, or unnecessary? Suggest a cleanup plan.

Practice

1. Look at a project you're working on and draw its file structure
2. Identify any files that are in the wrong place
3. Write a conventions document with naming and placement rules
4. In your next AI session, reference the conventions document in your first prompt

Key Takeaways

• Structure matters more as projects grow -- establish conventions early
• Create a conventions document and reference it in AI sessions
• Use consistent naming: PascalCase for components, camelCase for utils, kebab-case for directories
• Colocate related files (component + styles + tests in one folder)
• Start AI sessions with project context and be explicit about file paths

Next Up

Your project is well-structured and you know how to keep it that way. The last skill brings everything together: a repeatable process for fixing anything that goes wrong.

Continue to 2.4 The Debug Loop