Software Engineering
A project folder structure should make it obvious where a developer can find code, tests, configuration, assets and documentation. The goal is not to create the maximum number of folders; it is to keep responsibilities clear as the project grows.
The exact structure changes by framework and team. Start simple, follow the conventions of your stack, and introduce more layers only when they reduce confusion.
A simple frontend structure
For a React-style frontend, group reusable UI, page-level views, services and assets separately. Keep feature-specific code close together when the project becomes larger.
- src/components – reusable UI
- src/pages – route-level screens
- src/services – API calls
- src/assets – images and static files
- src/utils – shared helpers
A simple backend structure
A backend should separate HTTP routing from business logic and data access. This makes testing easier and prevents controllers from becoming large files that do everything.
- routes – endpoint definitions
- controllers – request/response handling
- services – business rules
- models or repositories – data access
- middleware – authentication, validation and shared request logic
Full stack monorepo example
For small teams, a single repository can contain frontend and backend applications with shared documentation and tooling at the root.
- apps/web – frontend application
- apps/api – backend application
- packages/shared – shared types or utilities when genuinely needed
- docs – architecture and setup notes
- .env.example – required environment variable names without secrets
Keep configuration predictable
Environment-specific values such as database credentials and API keys should not be hard-coded. Use environment variables and document the required keys in a safe example file.
- Never commit real secrets
- Keep production and development values separate
- Document startup commands in README
Name files by responsibility
Clear names reduce mental overhead. Prefer names that describe the feature or responsibility instead of generic files such as helpers2.js or finalController.js.
- user.service.js
- auth.middleware.js
- course.controller.js
- booking.repository.js
Common folder-structure mistakes
Over-engineering is as harmful as having no structure. Beginners often copy enterprise folder trees before the project needs them, which adds ceremony without improving maintainability.
- Too many empty layers
- Mixing UI, API and database logic in one file
- Duplicating utilities across features
- Storing secrets in the repository
- No README or setup instructions
When to refactor the structure
Refactor when developers repeatedly struggle to find code, files become too large, tests are hard to isolate or features are tightly coupled. Let real problems guide the architecture instead of guessing future complexity.