What Is a Project?

By the end of this lesson, you’ll be able to understand the basic structure of many AI-generated projects and identify the key files — no coding knowledge required.

The Mental Model: A Recipe Box

Before we look at a single file, let’s anchor this with something familiar.

A software project is like a recipe box you keep in your kitchen:

When an AI tool “scaffolds a project,” it is creating this box, writing the recipe cards, listing the ingredients, and going grocery shopping — all in seconds. Your job is to understand the box well enough to say “put the dessert recipe in the right section” or “we don’t need that ingredient anymore.”

The Simple Truth

A software project is a folder on your computer that contains organized files.

That’s it. It is not magical. It is not complicated. It is a folder. Inside that folder are files that work together to create something — a website, an app, a tool, a data dashboard.

When people say “I created a new project,” they mean: I made a folder and started putting files in it (or had an AI tool do it for them).

What’s Inside a Typical Project?

Here’s what a simple website project looks like:

my-website/
├── index.html          <- The main page
├── style.css           <- How it looks
├── app.js              <- What it does
├── README.md           <- Description of the project
└── package.json        <- Project configuration

And here’s a slightly more complex one with organized subfolders:

my-app/
├── src/                <- Source code folder
│   ├── index.html
│   ├── styles/
│   │   └── main.css
│   └── scripts/
│       └── app.js
├── public/             <- Static files (images, fonts)
│   └── logo.png
├── README.md
├── package.json
└── .gitignore          <- Tells git which files to ignore

Notice the pattern: the more organized version groups related files into subfolders. Styles go in styles/, scripts go in scripts/. This is the same principle behind organizing a filing cabinet — you would not throw every document into one drawer.

The Key Files You’ll See Everywhere

README.md

Every project should have a README. It is a plain text file (written in Markdown) that explains:

• What the project is
• How to set it up
• How to use it

When you browse GitHub, the README is the first thing you see. Think of it as the project’s front door — visitors read this before anything else.

package.json

This is the project’s ID card. It contains:

• The project’s name and version
• What other software it depends on (dependencies)
• Scripts for common tasks (run, build, test)

{
  "name": "my-website",
  "version": "1.0.0",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build"
  },
  "dependencies": {
    "astro": "^5.0.0"
  }
}

(In this example, “astro” is a web framework — your project might list different dependencies depending on what tools the AI chose. The structure is the same regardless.)

When you run npm install, it reads package.json and downloads everything the project needs. Think of it as handing a grocery list to a personal shopper — npm reads the list and fetches everything.

.gitignore

This tells git which files to not track. Common entries:

node_modules/       # Downloaded dependencies (huge, regeneratable)
.env                # Secret API keys
dist/               # Build output (regeneratable)
.DS_Store           # macOS junk files

You never commit node_modules/ or .env to git. The .gitignore file prevents this automatically. (A common practice is to commit a .env.example file with placeholder keys so collaborators know which variables are needed — but never commit the real .env with actual secrets.)

The node_modules Folder

After running npm install, you will see a node_modules folder appear. This contains all the downloaded dependencies your project needs. Some key facts:

• It can be enormous (hundreds of MB, thousands of files)
• You never edit files inside it
• You never commit it to git
• It is always regeneratable by running npm install
• If it gets corrupted: (1) delete the node_modules folder and run npm install again; (2) if still broken, verify your Node/npm version with node --version; (3) for existing projects, try npm ci for a clean install from the lockfile

Think of node_modules as the grocery bag from the recipe box analogy. You do not write on the grocery bags — you use the ingredients inside them. And if a bag goes bad, you throw it out and go shopping again with the same list (package.json).

Worked Example: Exploring a Real Project

Imagine you asked an AI CLI tool to create a research lab website. Here is what it produced. Let’s walk through it together:

chen-lab-site/
├── src/
│   ├── pages/
│   │   ├── index.astro          <- Homepage
│   │   ├── publications.astro   <- Publications page
│   │   └── team.astro           <- Team members page
│   ├── components/
│   │   ├── Header.astro         <- Site navigation
│   │   └── PaperCard.astro      <- Reusable publication card
│   ├── data/
│   │   └── papers.json          <- Publication data
│   └── styles/
│       └── global.css           <- Site-wide styles
├── public/
│   ├── headshots/               <- Team member photos
│   └── favicon.ico
├── package.json                 <- Dependencies and scripts
├── astro.config.mjs             <- Framework configuration
├── README.md                    <- Project description
└── .gitignore                   <- Files to exclude from git

Even without knowing how to code, you can read this structure and understand:

• Pages live in src/pages/ — the site has a homepage, publications page, and team page
• Reusable pieces live in src/components/ — a header and a card for papers
• Data lives in src/data/ — the publication list is stored as structured data
• Images live in public/headshots/ — photos are kept separate from code
• Configuration lives at the root — package.json, astro.config.mjs, etc.

This is the core skill: reading a project structure and knowing where things belong.

Try it yourself

Open your terminal and explore any project folder you have (or create a quick one):

# Create a minimal project to explore
mkdir my-test-project && cd my-test-project
npm init -y
ls

That npm init -y command generates a package.json — the “ID card” you just learned about. Run cat package.json to read it. If you have tree installed, run tree -L 2 to see the structure visually. Otherwise, ls -la shows all files including hidden ones.

When Things Go Wrong

Key Takeaways

• A project is just a folder with organized files — nothing more mysterious than that
• package.json is the ID card (name, dependencies, scripts); README.md is the front door (explains the project); .gitignore is the privacy filter (keeps secrets and junk out of git)
• node_modules is downloaded, enormous, and regeneratable — never edit it, never commit it
• When an AI creates a project, your job is to read the structure and verify that files are in logical places
• You direct the AI with structural knowledge: “put this in src/pages/” or “add a component in src/components/”