Everyone judges a repository by its root. If the first screen of ls already makes you want to close the tab, the rest of the project is going to hurt. Organizing a project is not busywork: it determines whether someone can contribute in an hour or in a week.
The project root is the first impression
The root is the cover. Anyone arriving opens it before any other file. Keep only a few things there: the README, license, lint/format configuration, package manager files, and top-level directories. Scattered configuration and fifty loose files in the root are noise—and noise hides what matters.
Organize by domain, not by type
The classic mistake is grouping by technical type: controllers/, services/, models/. It works in a tutorial, but becomes a treasure hunt in a real project because a single feature ends up scattered across five directories.
Group by domain: billing/, users/, reports/. Each directory tells you what the system does, not how it was coded. Bonus: changing a feature touches one directory, and the structure becomes free documentation for the business.
Monorepo or multirepo: choose, don’t leave it to chance
Monorepo: everything in one repository, one history, and refactoring can span packages at once. Great as long as the team and CI can handle it.
Multirepo: each service has its own repository, with independent ownership and deployments—at the cost of versioning the contract between them.
There is no universal winner. A small team with tightly coupled code: monorepo. Services with different life cycles and separate owners: multirepo. The only real mistake is failing to decide and letting chance choose for you.
README and docs: keep the map at the root
A README that only repeats the project’s name is a waste. It should answer three questions: what is this, how do I run it, and where can I find the rest? A setup command that actually works with copy and paste is worth more than any beautifully written paragraph.
Longer documentation belongs in docs/, linked from the README. The README is the map; docs/ is the territory. If the map is hidden, no one can find the way.
Conventions that run themselves
A rule that depends on someone remembering it does not exist. Put the linter and formatter in the repository, running on commit (pre-commit) and in CI. Adopt a commit convention—Conventional Commits will do—so the history becomes almost a changelog for free.
The idea is simple: the machine enforces the convention, not a colleague in a pull request. Arguing about commas in code review is time no one gets back.
Standardized scripts and the onboarding test
Every project needs the same verbs: install, run, test, and build. Use the same names in every repository (setup, dev, test, build), regardless of the stack underneath. No one should have to memorize the magical command specific to each project.
The final test is onboarding: hand the repository to someone who has never seen it and time how long it takes them to run it locally. Did they get stuck at any step? That is the hole in your structure, identified by a real user.
A good repository is not one you understand. It is one the next person understands without having to message you.
