What Is a Project?

The simple truth

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

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

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:

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

The key files you’ll see everywhere

README.md

Every project should have a README. It’s 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.

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"
  }
}

When you run npm install, it reads package.json and downloads everything the project needs.

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

The node_modules folder

After running npm install, you’ll 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’s always regeneratable by running npm install
• If it gets corrupted, delete it and run npm install again

The mental model

Think of a project as a recipe box:

When an AI tool “scaffolds a project,” it’s creating this box, putting in the recipe cards, and writing the ingredient list — all in seconds.