The shape of a project you did not lay out

Find the three landmarks

Open an unfamiliar project and you see thirty folders. Three of them tell you almost everything.

package.json: the project’s identity card. The scripts section tells you how to run it. The dependencies section tells you what it is built from. Reading those two lists takes a minute and tells you more than an hour of clicking through folders.

The entry point. Where execution begins. app/layout.tsx and app/page.tsx in a Next.js app router project. src/main.tsx in a Vite app. manage.py and urls.py in Django. app.py in Flask.

The routes folder. Where URLs map to code. In Next.js the folder structure is the URL: app/bookings/[id]/page.tsx serves /bookings/71. In Express or Flask it is a list of paths in one file. Once you can go from a URL to a file, you can navigate anything.

The folders you can ignore

node_modules: downloaded libraries. Hundreds of megabytes, thousands of files, none of them yours. Never edit anything in here; it is deleted and recreated by npm install.

.next, dist, build, .venv, __pycache__: generated output. Also never edited by hand.

public or static: files served exactly as they are. Images, fonts, favicon.ico. Anything here is public to the whole internet, which is worth remembering before you put a spreadsheet in it.

When an agent reports that it edited something in node_modules or .next, that change will vanish on the next install or build. Say so, and ask for the real fix.

The files that decide behaviour

• .env / .env.local: secrets and configuration. Never committed. If you can see this file in a public repository, you have an incident, not a question.
• .gitignore: what git deliberately ignores. .env and node_modules must be in it.
• package-lock.json / pnpm-lock.yaml / requirements.txt: exact versions. Committed, never hand-edited.
• tsconfig.json, next.config.js, tailwind.config.js: build and framework settings. Small files with large effects.
• drizzle/ or migrations/ or prisma/schema.prisma: the database’s shape and history.

A layout worth imposing

Generated projects drift into disorder because each request is answered locally. Deciding the shape yourself, once, and writing it in the rules file is what keeps it navigable:

app/            pages and API routes only
components/     things that draw. No database access, ever.
lib/            logic. queries.ts, dates.ts, money.ts, slots.ts
drizzle/        schema and migrations
scripts/        one-off jobs you run by hand

The second line is the one that prevents an entire failure class. A component that runs in the browser must not import anything that talks to the database: do it and you either leak server code into the browser bundle or break the build in a way that is very hard to read. Making it a folder rule means you can check it by looking rather than by reasoning.

Two commands that map anything

# The structure, ignoring the noise
find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | head -40

# Where is this concept mentioned?
grep -rn "overlap" --include="*.ts" --include="*.tsx" . | grep -v node_modules

The second is how you find a rule when you do not know where it lives. Search for the domain word (overlap, refund, cancel) rather than for a function name you would have to already know.

If grep returns three files for one rule, that is a finding in itself: the rule exists in three places and they may not agree.

The README is worth ten minutes

Most generated projects ship a README describing a framework rather than your app, and everybody ignores it forever. Replace it once with five lines: what this app is for, how to run it, what has to be in .env, how to reset the database, and where the deployed version lives.

You are writing it for yourself in four months, when you have forgotten which command starts the thing. That is not a hypothetical reader. It is the most likely one, and the ten minutes will feel like a gift.

Ask for the map

Give me a one-line description of every folder in this project,
and name the single file where a booking is written to the database.

An agent that has read the project answers this in seconds. If the answer names a file that does not exist, you have learned something important about how much it currently knows, and the right response is to point at the real file rather than to argue.