How to structure your backend project

Project structure is one of the first things experienced engineers evaluate when reviewing code. A well-structured project signals that you understand separation of concerns, maintainability, and professional development practices.

Why structure matters

A common mistake junior developers make is putting everything in a few large files. While this works for small scripts, it breaks down quickly as complexity grows. Poor structure makes code harder to test, review, and extend.

The layered architecture

For most backend projects, a layered architecture works well:

src/
  controllers/    # Handle HTTP requests and responses
  services/       # Business logic
  repositories/   # Data access
  models/         # Data structures
  middleware/     # Cross-cutting concerns
  config/        # Configuration
  utils/         # Shared utilities
tests/
  unit/
  integration/

Each layer has a single responsibility and depends only on the layer below it. Controllers call services, services call repositories, and repositories interact with the database.

Key principles

1. Single Responsibility

Each file should do one thing. A controller handles the HTTP layer. A service handles business logic. Mixing these responsibilities creates tightly coupled code.

2. Dependency injection

Pass dependencies as parameters rather than importing them directly. This makes testing straightforward because you can inject mock implementations.

3. Configuration management

Never hardcode configuration values. Use environment variables and a config module that validates required values at startup.

4. Error handling

Create custom error classes and a centralized error handler. Each layer should throw meaningful errors, and the controller layer should translate them into appropriate HTTP responses.

The README test

If you can write a clear README that explains your project structure, your architecture is probably sound. Document why you organized code the way you did, and what each directory contains.