Structuring a Repo So a New Developer Can Find Things

A repo layout is documentation whether you write it that way or not. A new developer opens it and forms an idea of how the system is put together from the folder names. If that idea is wrong, or if there is no idea to form because everything is in one flat pile, every task starts with a hunt.

Group by feature, not by kind

The common early layout puts all components in one folder, all API handlers in another, all tests in a third. It looks tidy and it means a single feature is smeared across the entire tree. To change how billing works you touch six folders and hope you found them all.

Group by feature instead. A billing folder holds the billing screens, the billing logic, the billing API calls and the billing tests. Someone working on billing works in one place, and someone new can guess where billing lives because it is called billing.

Name folders after the product, not the framework

The folders should read like the words the team uses in conversation: accounts, invoices, notifications, reports. Not utils, helpers, services, managers, which tell you nothing about what is inside. If you would not say the folder name in a stand-up, it is probably the wrong name.

Keep shared code small and policed

There will be genuinely shared things: the design system components, the API client, formatting helpers. Put them in one clearly named place and hold a line: it only holds code used by more than one feature. The moment “I might reuse this later” gets something in, the shared folder starts growing into a second copy of the app.

One obvious entry point

There should be a single, findable place that shows how the app starts, how routing works, and how the top-level pieces connect. A new developer reads that first and has a map. Bury it and they build the map by trial and error.

A short readme that stays true

Not a manual. The handful of things people keep asking: how to run it locally, how to run the tests, how a change gets deployed, and a paragraph on how the main parts fit together. Keep it in the repo so it is updated alongside the code, and delete anything in it that has gone stale rather than leaving a confident wrong answer.

The test

Hand the repo to someone who has never seen it and ask them to find where a named feature is implemented. If they can do it in a minute from the folder names alone, the structure is doing its job. If they need you, the structure needs work.

Common questions

Organise by type or by feature?

By feature, once the project is past its first few weeks. Grouping all components, all services and all tests separately spreads a single feature across the whole tree.

Where should shared code go?

A clearly named shared or common area, with a rule that it only holds things used by more than one feature. Without the rule it becomes a dumping ground.

Does a monorepo change this?

The same principles apply within each package. A monorepo adds a top level of “which app or library” but the inside of each still wants feature grouping.