Project Structure for an Express and Mongoose API

A well-organised project structure is not a cosmetic concern — it determines how fast you can add features, how easily a new developer can understand the codebase, and how clearly responsibilities are separated across files. By the time you finish this chapter, your MERN Blog server will be a fully working REST API backed by MongoDB. In this lesson you will design the complete folder structure that will hold all of that code — the models, routes, controllers, middleware, config, and utilities — and understand the responsibility of each layer.

The Complete Server Folder Structure #

server/
├── index.js                      ← Entry point: loads env, connects DB, starts HTTP server
├── .env                          ← Secrets (never commit)
├── .env.example                  ← Template with placeholder values (commit this)
├── .gitignore
├── nodemon.json
├── package.json
│
└── src/
    ├── config/
    │   └── db.js                 ← Mongoose connect/disconnect module
    │
    ├── models/
    │   ├── User.js               ← User schema + model
    │   ├── Post.js               ← Post schema + model
    │   └── Comment.js            ← Comment schema + model
    │
    ├── controllers/
    │   ├── authController.js     ← register, login, logout, getMe, forgotPassword...
    │   ├── postController.js     ← getAllPosts, getPostById, createPost, updatePost, deletePost
    │   ├── userController.js     ← getUserProfile, updateProfile, deleteAccount
    │   └── commentController.js  ← getComments, createComment, updateComment, deleteComment
    │
    ├── routes/
    │   ├── auth.js               ← Express Router for /api/auth/*
    │   ├── posts.js              ← Express Router for /api/posts/*
    │   ├── users.js              ← Express Router for /api/users/*
    │   └── comments.js           ← Express Router for /api/posts/:id/comments/*
    │
    ├── middleware/
    │   ├── auth.js               ← JWT protect middleware
    │   ├── authorize.js          ← Role-based access control factory
    │   ├── validate.js           ← express-validator error collector
    │   ├── validateObjectId.js   ← MongoDB ObjectId format checker
    │   ├── notFound.js           ← 404 catch-all
    │   └── errorHandler.js       ← Global error handler (4 args)
    │
    ├── validators/
    │   ├── authValidators.js     ← register and login validation rules
    │   └── postValidators.js     ← createPost and updatePost validation rules
    │
    └── utils/
        ├── AppError.js           ← Custom error class with statusCode
        ├── asyncHandler.js       ← Async route wrapper for Express 4
        └── sendEmail.js          ← Nodemailer email sending utility

The Entry Point — index.js #

// server/index.js — clean, minimal entry point
require('dotenv').config();

const express    = require('express');
const cors       = require('cors');
const helmet     = require('helmet');
const morgan     = require('morgan');
const rateLimit  = require('express-rate-limit');
const connectDB  = require('./src/config/db');

const app  = express();
const PORT = process.env.PORT || 5000;

// ── Security and utility middleware ────────────────────────────────────────────
app.use(helmet());
app.use(cors({
  origin:      process.env.CLIENT_URL || 'http://localhost:5173',
  credentials: true,
}));
if (process.env.NODE_ENV === 'development') app.use(morgan('dev'));
app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 200 }));
app.use(express.json({ limit: '1mb' }));
app.use(express.urlencoded({ extended: false }));

// ── API Routes ─────────────────────────────────────────────────────────────────
app.use('/api/auth',  require('./src/routes/auth'));
app.use('/api/posts', require('./src/routes/posts'));
app.use('/api/users', require('./src/routes/users'));

// ── Health check ───────────────────────────────────────────────────────────────
app.get('/api/health', (req, res) => {
  res.json({ status: 'ok', env: process.env.NODE_ENV });
});

// ── Error handling (always last) ───────────────────────────────────────────────
app.use(require('./src/middleware/notFound'));
app.use(require('./src/middleware/errorHandler'));

// ── Connect DB then start server ───────────────────────────────────────────────
const start = async () => {
  await connectDB();
  app.listen(PORT, () => console.log(`Server → http://localhost:${PORT}`));
};

start().catch(err => { console.error(err); process.exit(1); });

Responsibility Mapping #

Common Mistakes #

Mistake 1 — Putting Mongoose queries directly in route files #

❌ Wrong — routes doing database work:

// routes/posts.js
router.get('/', async (req, res) => {
  const posts = await Post.find({ published: true }).populate('author');
  res.json({ data: posts });
});
// Route file now has business logic — hard to test, hard to reuse

✅ Correct — route files stay thin; all logic is in controller files:

// routes/posts.js
router.get('/', getAllPosts); // ← just the mapping

// controllers/postController.js
const getAllPosts = asyncHandler(async (req, res) => {
  const posts = await Post.find({ published: true }).populate('author');
  res.json({ data: posts });
});

Mistake 2 — Importing models in route files instead of controllers #

❌ Wrong — routes importing models directly:

// routes/posts.js
const Post = require('../models/Post'); // model imported into route file
router.get('/', async (req, res) => { const posts = await Post.find()... });

✅ Correct — only controller files import models:

// controllers/postController.js
const Post = require('../models/Post'); // model belongs in controller ✓

Mistake 3 — Inconsistent import paths caused by poor folder structure #

❌ Wrong — deep relative paths that break when files are moved:

const AppError = require('../../../utils/AppError'); // fragile relative path

✅ Correct — keep the structure flat (max 2 levels deep in src/) and consistent:

const AppError = require('../utils/AppError'); // one level up from controllers/ ✓

Quick Reference — File Creation Checklist #