MERN Stack: The Complete Guide to MongoDB, Express, React, and Node.js

// MERN Stack Architecture Overview
// Each layer communicates through well-defined interfaces

// ============================================
// Layer 1: MongoDB — Data Layer
// ============================================

import { MongoClient, ObjectId } from 'mongodb';

class DatabaseConnection {
  constructor(uri, dbName) {
    this.uri = uri;
    this.dbName = dbName;
    this.client = null;
    this.db = null;
  }

  async connect() {
    if (this.db) return this.db;

    this.client = new MongoClient(this.uri, {
      maxPoolSize: 100,
      minPoolSize: 10,
      maxIdleTimeMS: 30000,
      serverSelectionTimeoutMS: 5000,
      connectTimeoutMS: 10000,
    });

    await this.client.connect();
    this.db = this.client.db(this.dbName);
    console.log(`Connected to MongoDB: ${this.dbName}`);
    return this.db;
  }

  async disconnect() {
    if (this.client) {
      await this.client.close();
      this.db = null;
      this.client = null;
    }
  }

  getCollection(name) {
    if (!this.db) throw new Error('Database not connected');
    return this.db.collection(name);
  }
}

// ============================================
// Layer 2: Express.js — API Layer
// ============================================

import express from 'express';
import cors from 'cors';
import helmet from 'helmet';

class ApiServer {
  constructor(dbConnection) {
    this.app = express();
    this.db = dbConnection;
    this.setupMiddleware();
    this.setupRoutes();
    this.setupErrorHandling();
  }

  setupMiddleware() {
    this.app.use(helmet());
    this.app.use(cors({
      origin: process.env.CLIENT_URL || 'http://localhost:3000',
      credentials: true,
    }));
    this.app.use(express.json({ limit: '10mb' }));
    this.app.use(express.urlencoded({ extended: true }));
  }

  setupRoutes() {
    this.app.get('/api/health', (req, res) => {
      res.json({ status: 'ok', timestamp: new Date().toISOString() });
    });

    this.app.use('/api/users', this.userRoutes());
    this.app.use('/api/products', this.productRoutes());
    this.app.use('/api/orders', this.orderRoutes());
  }

  userRoutes() {
    const router = express.Router();

    router.get('/', async (req, res, next) => {
      try {
        const users = await this.db
          .getCollection('users')
          .find({}, { projection: { password: 0 } })
          .toArray();
        res.json(users);
      } catch (error) {
        next(error);
      }
    });

    router.get('/:id', async (req, res, next) => {
      try {
        const user = await this.db
          .getCollection('users')
          .findOne({ _id: new ObjectId(req.params.id) });
        if (!user) return res.status(404).json({ error: 'User not found' });
        res.json(user);
      } catch (error) {
        next(error);
      }
    });

    return router;
  }

  productRoutes() {
    const router = express.Router();

    router.get('/', async (req, res, next) => {
      try {
        const { page = 1, limit = 20, category } = req.query;
        const filter = category ? { category } : {};
        const products = await this.db
          .getCollection('products')
          .find(filter)
          .skip((page - 1) * limit)
          .limit(parseInt(limit))
          .toArray();
        res.json(products);
      } catch (error) {
        next(error);
      }
    });

    return router;
  }

  orderRoutes() {
    const router = express.Router();

    router.post('/', async (req, res, next) => {
      try {
        const order = {
          ...req.body,
          createdAt: new Date(),
          status: 'pending',
        };
        const result = await this.db
          .getCollection('orders')
          .insertOne(order);
        res.status(201).json({ orderId: result.insertedId });
      } catch (error) {
        next(error);
      }
    });

    return router;
  }

  setupErrorHandling() {
    this.app.use((err, req, res, next) => {
      console.error(`Error: ${err.message}`, {
        path: req.path,
        method: req.method,
        stack: err.stack,
      });

      res.status(err.status || 500).json({
        error: process.env.NODE_ENV === 'production'
          ? 'Internal server error'
          : err.message,
      });
    });
  }

  start(port = 5000) {
    return new Promise((resolve) => {
      this.server = this.app.listen(port, () => {
        console.log(`API server running on port ${port}`);
        resolve(this.server);
      });
    });
  }

  async stop() {
    if (this.server) {
      return new Promise((resolve) => this.server.close(resolve));
    }
  }
}

// ============================================
// Application Bootstrap
// ============================================

async function bootstrap() {
  const db = new DatabaseConnection(
    process.env.MONGODB_URI || 'mongodb://localhost:27017',
    process.env.DB_NAME || 'mern_app'
  );

  await db.connect();

  const server = new ApiServer(db);
  await server.start(process.env.PORT || 5000);

  // Graceful shutdown
  const shutdown = async () => {
    console.log('Shutting down gracefully...');
    await server.stop();
    await db.disconnect();
    process.exit(0);
  };

  process.on('SIGTERM', shutdown);
  process.on('SIGINT', shutdown);
}

bootstrap().catch(console.error);

// MERN Data Flow — Request lifecycle from React to MongoDB

// ============================================
// React Client — API Service Layer
// ============================================

class ApiService {
  constructor(baseURL) {
    this.baseURL = baseURL;
    this.token = null;
  }

  setToken(token) {
    this.token = token;
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseURL}${endpoint}`;
    const headers = {
      'Content-Type': 'application/json',
      ...(this.token && { Authorization: `Bearer ${this.token}` }),
      ...options.headers,
    };

    const response = await fetch(url, {
      ...options,
      headers,
    });

    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new ApiError(response.status, error.message || 'Request failed');
    }

    return response.json();
  }

  get(endpoint) {
    return this.request(endpoint, { method: 'GET' });
  }

  post(endpoint, data) {
    return this.request(endpoint, {
      method: 'POST',
      body: JSON.stringify(data),
    });
  }

  put(endpoint, data) {
    return this.request(endpoint, {
      method: 'PUT',
      body: JSON.stringify(data),
    });
  }

  delete(endpoint) {
    return this.request(endpoint, { method: 'DELETE' });
  }
}

class ApiError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

// ============================================
// React Component — Consuming the API
// ============================================

// Note: This is a conceptual example showing the pattern
// In real React code, use useState, useEffect, and proper hooks

function useProducts(api, category) {
  // State: products, loading, error
  // Effect: fetch products on mount and category change
  // Returns: { products, loading, error, refetch }

  const fetchProducts = async () => {
    try {
      const endpoint = category
        ? `/api/products?category=${encodeURIComponent(category)}`
        : '/api/products';
      const data = await api.get(endpoint);
      return { products: data, error: null };
    } catch (err) {
      return { products: [], error: err.message };
    }
  };

  return { fetchProducts };
}

// ============================================
// Express Middleware — Request Pipeline
// ============================================

import jwt from 'jsonwebtoken';

function createAuthMiddleware(secret) {
  return (req, res, next) => {
    const authHeader = req.headers.authorization;

    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    const token = authHeader.split(' ')[1];

    try {
      const decoded = jwt.verify(token, secret);
      req.user = decoded;
      next();
    } catch (err) {
      if (err.name === 'TokenExpiredError') {
        return res.status(401).json({ error: 'Token expired' });
      }
      return res.status(401).json({ error: 'Invalid token' });
    }
  };
}

function createValidationMiddleware(schema) {
  return (req, res, next) => {
    const { error } = schema.validate(req.body);
    if (error) {
      return res.status(400).json({
        error: 'Validation failed',
        details: error.details.map(d => d.message),
      });
    }
    next();
  };
}

function requestLogger(req, res, next) {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(JSON.stringify({
      method: req.method,
      path: req.path,
      status: res.statusCode,
      duration_ms: duration,
      user: req.user?.id || 'anonymous',
    }));
  });

  next();
}

// ============================================
// MongoDB — Query Layer with Error Handling
// ============================================

class ProductRepository {
  constructor(db) {
    this.collection = db.collection('products');
  }

  async findById(id) {
    const product = await this.collection.findOne({ _id: new ObjectId(id) });
    if (!product) throw new NotFoundError('Product not found');
    return product;
  }

  async findWithPagination(filter = {}, page = 1, limit = 20) {
    const skip = (page - 1) * limit;

    const [products, total] = await Promise.all([
      this.collection
        .find(filter)
        .sort({ createdAt: -1 })
        .skip(skip)
        .limit(limit)
        .toArray(),
      this.collection.countDocuments(filter),
    ]);

    return {
      data: products,
      pagination: {
        page,
        limit,
        total,
        pages: Math.ceil(total / limit),
      },
    };
  }

  async create(productData) {
    const product = {
      ...productData,
      createdAt: new Date(),
      updatedAt: new Date(),
    };

    const result = await this.collection.insertOne(product);
    return { ...product, _id: result.insertedId };
  }

  async updateById(id, updateData) {
    const result = await this.collection.findOneAndUpdate(
      { _id: new ObjectId(id) },
      { $set: { ...updateData, updatedAt: new Date() } },
      { returnDocument: 'after' }
    );

    if (!result) throw new NotFoundError('Product not found');
    return result;
  }
}

class NotFoundError extends Error {
  constructor(message) {
    super(message);
    this.status = 404;
  }
}

mern-app/
├── client/                          # React frontend
│   ├── public/
│   │   ├── index.html
│   │   └── favicon.ico
│   ├── src/
│   │   ├── components/              # Reusable UI components
│   │   │   ├── common/              # Buttons, inputs, modals
│   │   │   ├── layout/              # Header, footer, sidebar
│   │   │   └── features/            # Feature-specific components
│   │   ├── pages/                   # Route-level page components
│   │   ├── hooks/                   # Custom React hooks
│   │   ├── services/                # API service layer
│   │   │   ├── api.js               # Base API client
│   │   │   ├── authService.js
│   │   │   ├── productService.js
│   │   │   └── orderService.js
│   │   ├── context/                 # React context providers
│   │   ├── utils/                   # Client-side utilities
│   │   ├── App.jsx
│   │   └── index.jsx
│   ├── package.json
│   └── .env.production
│
├── server/                          # Express backend
│   ├── src/
│   │   ├── config/                  # Configuration files
│   │   │   ├── database.js          # MongoDB connection
│   │   │   ├── env.js               # Environment validation
│   │   │   └── cors.js              # CORS configuration
│   │   ├── middleware/              # Express middleware
│   │   │   ├── auth.js              # JWT authentication
│   │   │   ├── validate.js          # Request validation
│   │   │   ├── errorHandler.js      # Global error handler
│   │   │   └── rateLimiter.js       # Rate limiting
│   │   ├── routes/                  # Route definitions
│   │   │   ├── index.js             # Route aggregator
│   │   │   ├── userRoutes.js
│   │   │   ├── productRoutes.js
│   │   │   └── orderRoutes.js
│   │   ├── controllers/             # Request handlers
│   │   │   ├── userController.js
│   │   │   ├── productController.js
│   │   │   └── orderController.js
│   │   ├── services/                # Business logic
│   │   │   ├── userService.js
│   │   │   ├── productService.js
│   │   │   ├── orderService.js
│   │   │   └── emailService.js
│   │   ├── repositories/            # Data access layer
│   │   │   ├── userRepository.js
│   │   │   ├── productRepository.js
│   │   │   └── orderRepository.js
│   │   ├── models/                  # Mongoose schemas (if using Mongoose)
│   │   │   ├── User.js
│   │   │   ├── Product.js
│   │   │   └── Order.js
│   │   ├── utils/                   # Server utilities
│   │   │   ├── logger.js
│   │   │   ├── errors.js            # Custom error classes
│   │   │   └── validators.js        # Joi/Zod schemas
│   │   └── app.js                   # Express app setup
│   ├── tests/
│   │   ├── unit/
│   │   ├── integration/
│   │   └── fixtures/
│   ├── package.json
│   └── .env
│
├── shared/                          # Shared code between client and server
│   ├── types/                       # TypeScript types (if using TS)
│   ├── constants/                   # Shared constants
│   ├── validation/                  # Shared validation schemas
│   └── utils/                       # Shared utility functions
│
├── docker-compose.yml               # Local development environment
├── Dockerfile.client
├── Dockerfile.server
├── .github/workflows/ci.yml         # CI/CD pipeline
├── package.json                     # Root package.json for monorepo
└── README.md

import jwt from 'jsonwebtoken';
import bcrypt from 'bcrypt';
import crypto from 'crypto';

// ============================================
// Authentication Service
// ============================================

class AuthService {
  constructor(userRepository, config) {
    this.userRepo = userRepository;
    this.accessTokenSecret = config.accessTokenSecret;
    this.refreshTokenSecret = config.refreshTokenSecret;
    this.accessTokenExpiry = config.accessTokenExpiry || '15m';
    this.refreshTokenExpiry = config.refreshTokenExpiry || '7d';
    this.saltRounds = config.saltRounds || 12;
  }

  async register(email, password, name) {
    // Check if user exists
    const existing = await this.userRepo.findByEmail(email);
    if (existing) {
      throw new ConflictError('Email already registered');
    }

    // Hash password
    const hashedPassword = await bcrypt.hash(password, this.saltRounds);

    // Create user
    const user = await this.userRepo.create({
      email,
      password: hashedPassword,
      name,
      createdAt: new Date(),
    });

    // Generate tokens
    const tokens = this.generateTokens(user);

    // Store refresh token hash
    await this.storeRefreshToken(user._id, tokens.refreshToken);

    return {
      user: this.sanitizeUser(user),
      ...tokens,
    };
  }

  async login(email, password) {
    const user = await this.userRepo.findByEmail(email);
    if (!user) {
      throw new UnauthorizedError('Invalid credentials');
    }

    const validPassword = await bcrypt.compare(password, user.password);
    if (!validPassword) {
      throw new UnauthorizedError('Invalid credentials');
    }

    const tokens = this.generateTokens(user);
    await this.storeRefreshToken(user._id, tokens.refreshToken);

    return {
      user: this.sanitizeUser(user),
      ...tokens,
    };
  }

  async refreshAccessToken(refreshToken) {
    try {
      const decoded = jwt.verify(refreshToken, this.refreshTokenSecret);

      // Verify refresh token exists in database
      const storedToken = await this.userRepo.getRefreshToken(decoded.userId);
      if (!storedToken || storedToken !== this.hashToken(refreshToken)) {
        throw new UnauthorizedError('Invalid refresh token');
      }

      // Generate new access token
      const user = await this.userRepo.findById(decoded.userId);
      const accessToken = this.generateAccessToken(user);

      return { accessToken };
    } catch (err) {
      throw new UnauthorizedError('Invalid refresh token');
    }
  }

  async logout(userId, refreshToken) {
    await this.userRepo.removeRefreshToken(userId);
  }

  generateTokens(user) {
    const accessToken = this.generateAccessToken(user);
    const refreshToken = jwt.sign(
      { userId: user._id.toString(), type: 'refresh' },
      this.refreshTokenSecret,
      { expiresIn: this.refreshTokenExpiry }
    );

    return { accessToken, refreshToken };
  }

  generateAccessToken(user) {
    return jwt.sign(
      {
        userId: user._id.toString(),
        email: user.email,
        type: 'access',
      },
      this.accessTokenSecret,
      { expiresIn: this.accessTokenExpiry }
    );
  }

  async storeRefreshToken(userId, token) {
    const hashedToken = this.hashToken(token);
    await this.userRepo.setRefreshToken(userId, hashedToken);
  }

  hashToken(token) {
    return crypto.createHash('sha256').update(token).digest('hex');
  }

  sanitizeUser(user) {
    const { password, refreshToken, ...safe } = user;
    return safe;
  }
}

// ============================================
// Security Middleware Stack
// ============================================

import rateLimit from 'express-rate-limit';
import mongoSanitize from 'express-mongo-sanitize';

function createSecurityMiddleware() {
  return [
    // Rate limiting — prevent brute force
    rateLimit({
      windowMs: 15 * 60 * 1000, // 15 minutes
      max: 100, // limit each IP to 100 requests per window
      standardHeaders: true,
      legacyHeaders: false,
      message: { error: 'Too many requests, please try again later' },
    }),

    // MongoDB injection prevention
    mongoSanitize(),

    // Additional security headers
    (req, res, next) => {
      res.setHeader('X-Content-Type-Options', 'nosniff');
      res.setHeader('X-Frame-Options', 'DENY');
      res.setHeader('X-XSS-Protection', '1; mode=block');
      res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
      next();
    },
  ];
}

class UnauthorizedError extends Error {
  constructor(message) {
    super(message);
    this.status = 401;
  }
}

class ConflictError extends Error {
  constructor(message) {
    super(message);
    this.status = 409;
  }
}

export { AuthService, createSecurityMiddleware };

# Docker Compose for MERN Stack Development
# Production uses separate managed services for each component

version: '3.8'

services:
  client:
    build:
      context: ./client
      dockerfile: Dockerfile
    ports:
      - '3000:3000'
    environment:
      - REACT_APP_API_URL=http://localhost:5000/api
    depends_on:
      - server
    volumes:
      - ./client/src:/app/src

  server:
    build:
      context: ./server
      dockerfile: Dockerfile
    ports:
      - '5000:5000'
    environment:
      - NODE_ENV=development
      - MONGODB_URI=mongodb://mongo:27017/mern_app
      - JWT_SECRET=dev-secret-change-in-production
      - CLIENT_URL=http://localhost:3000
    depends_on:
      mongo:
        condition: service_healthy
    volumes:
      - ./server/src:/app/src
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:5000/api/health']
      interval: 30s
      timeout: 10s
      retries: 3

  mongo:
    image: mongo:7
    ports:
      - '27017:27017'
    environment:
      - MONGO_INITDB_ROOT_USERNAME=admin
      - MONGO_INITDB_ROOT_PASSWORD=dev-password
      - MONGO_INITDB_DATABASE=mern_app
    volumes:
      - mongo_data:/data/db
      - ./server/scripts/init-db.js:/docker-entrypoint-initdb.d/init.js
    healthcheck:
      test: ['CMD', 'mongosh', '--eval', 'db.adminCommand({ ping: 1 })']
      interval: 10s
      timeout: 5s
      retries: 5

  mongo-express:
    image: mongo-express:latest
    ports:
      - '8081:8081'
    environment:
      - ME_CONFIG_MONGODB_ADMINUSERNAME=admin
      - ME_CONFIG_MONGODB_ADMINPASSWORD=dev-password
      - ME_CONFIG_MONGODB_SERVER=mongo
    depends_on:
      - mongo

volumes:
  mongo_data: