The Folders You'll Always See

The top level is a lobby

When you open almost any modern web app — Next.js, Astro, even a well-organized Express project — you see a handful of folders that show up over and over again. Different names, same jobs.

The top level of a project is like the lobby of a building. Most of what you see there isn't the actual work — it's information about the building. Configuration files, instructions, lists of what the project needs to run. The actual work happens deeper inside.

Here's what PetKarma's top level looks like:

pet-karma/
├── .claude/
├── .vscode/
├── app/
├── components/
├── docs/
├── hooks/
├── inspo/
├── lib/
├── migrations/
├── public/
└── services/

Let's walk through what each one is for.

src (or its equivalent)

In many projects you'll see a folder called src — short for source. It's where the majority of your deployable app lives: pages, components, hooks, libs, the things that actually make the app be the app.

If the top level is the lobby, src is where you go through the doors and the real work starts.

PetKarma doesn't use an src folder — its source code lives directly at the root under app/, components/, hooks/, etc. Opsette has both src/ and top-level folders because of migration history. Either pattern is valid. You'll know which one the project uses the moment you open it.

app — the routing folder

In modern Next.js, app is where your pages live. The folder structure inside app is your URL structure. A folder called dashboard becomes /dashboard. That's called file-based routing, and we'll get deeper into it on the next page.

Older Next.js projects used a folder called pages for the same job. Same concept, different convention.

components — reusable UI pieces

Components are the reusable pieces that pages are assembled from. Buttons, cards, nav bars, sections that wrap smaller pieces.

The key word is reusable — a component is something that could appear in more than one place without being rewritten.

hooks — reusable logic

A hook is a reusable piece of logic. Not a reusable piece of UI — that's a component. A hook is the behavior without the visual.

If you find yourself writing the same logic in three different pages — like fetching a user's friends list — you pull that out into a hook. Now all three pages can call the hook instead of each containing that logic themselves.

That's why you've seen business logic living in hooks. It belongs there when it's logic multiple places need. Logic sitting directly inside components or pages can't be reused and is hard to find — it's hiding.

lib — general utilities

Lib — short for library — is for code that's useful to the whole app but doesn't belong to any specific feature. Not a page. Not a component. Not a hook tied to a domain. Just shared tools.

Date formatters. Math helpers. Constants. Configuration values that are so general they don't belong anywhere else.

Date utils are the textbook example. Formatting a date isn't about friends, pets, appointments, or any specific thing — it's just something the whole app needs to do consistently.

services — talking to the outside world

Services is a folder that sits near hooks and lib but has its own job. A service is code that talks to something external.

Your Supabase client setup. A file that handles sending push notifications. A wrapper around third-party API calls.

Services are the layer between your app and everything outside it. Not every project has one — Opsette doesn't use a top-level services folder, because its API routes handle that job instead. You'll see both patterns.

public — static assets

Images, fonts, icons. Things that don't change and just need to be served directly to the browser. Nothing dynamic. Nothing computed. Just files.

The dotfolders (.claude, .vscode)

Folders that start with a dot are hidden configuration. .claude is your Claude Code instructions. .vscode is your VS Code settings. These are tool configs — you don't need to go in there to build the app.

Locking this in

Inside a typical project you have:

• src — source code container (sometimes skipped, source lives at root)
• app — the routing folder. File structure becomes URL structure.
• components — reusable UI. Things you can see.
• hooks — reusable logic. Things you can't see.
• lib — general utilities. So broad they don't belong to any feature.
• services — code that talks to external systems.
• public — static assets served directly.
• Dotfolders — tool configuration. Ignore unless configuring tools.

That's the map. Now let's open app and see how routing actually works.