MERN Authentication System

A robust, production-ready full-stack authentication system built with the MERN stack (MongoDB, Express, React, Node.js). This system implements industry-standard security practices, including HttpOnly cookies, Zod validation, and containerized deployment.

---

🏗️ System Architecture

graph TD
    User((User)) <--> Client[React Frontend]
    Client <--> API[Express Server]
    API <--> Auth[JWT + HttpOnly Cookies]
    API <--> Validation[Zod Schemas]
    API <--> DB[(MongoDB)]
    API <--> Mail[Nodemailer / SMTP]

Loading

---

🚀 Getting Started

1. Prerequisites

• Node.js (v18+)
• Docker & Docker Compose

2. Environment Configuration

Backend (server/.env): Create a .env file in the server directory (see server/.env.example for reference):

PORT=5000
MONGODB_URI="mongodb://127.0.0.1:27017/mern-auth"
JWT_SECRET="your_secret_key"
NODE_ENV="development"

SMTP_HOST=your_smtp_host
SMTP_PORT=587
SMTP_USER=your_username
SMTP_PASS=your_password
SENDER_EMAIL=your_email

Frontend (client/.env): Create a .env file in the client directory (see client/.env.example for reference):

VITE_BACKEND_URL="http://localhost:5000"

3. Run the Application

Option A: Docker (Recommended)

Rebuild and start the entire stack in seconds:

docker compose up --build -d

• Frontend: http://localhost
• Backend: http://localhost:5000

Option B: Manual Local Development

Backend:

cd server && npm install && npm run dev

Frontend:

cd client && npm install && npm run dev

• Accessible at: http://localhost:5173

---

🔐 Key Features

🔐 Authentication & Security

• JWT & HttpOnly Cookies: Secure session management protected against XSS.
• Zod Validation: Strict schema-based validation for all API requests and environment variables.
• Rate Limiting: Brute-force protection on sensitive authentication routes.
• Security Headers: Powered by Helmet to secure Express apps.
• CORS & Sanitization: Configured for cross-origin security and input sanitization.

📧 Email System

• Professional Templates: Luxury HTML email templates for Welcomes, OTPs, and Password Resets.
• Verification Flow: Secure account verification via 6-digit OTP.
• Password Recovery: Seamless reset flow with time-limited OTPs.

🎨 UI / UX

• Modern Dark Theme: Premium dark-mode design using TailwindCSS v4.
• Responsive Layout: Optimized for all device sizes.
• Protected Routes: Client-side route guards for authenticated sessions.
• Smooth Feedback: Toast notifications and loading states for a better user experience.

🐳 DevOps

• Dockerized Environment: docker-compose for the entire stack (Database & Server).
• Environment Management: Centralized config with Zod-validated .env files.

---

🛠️ Tech Stack

Category	Technology
Frontend	React 19, React Router v7, Axios, TailwindCSS v4
Backend	Node.js, Express.js, Zod
Database	MongoDB (Local Docker instance)
Security	JWT, BcryptJS, Helmet, Express-Rate-Limit
Email	Nodemailer, HTML Templates
DevOps	Docker, Docker Compose

---

📂 Project Structure

mern-auth-system/
├── client/                 # React frontend
│   ├── src/
│   │   ├── components/     # UI Components
│   │   ├── context/        # Auth Context
│   │   └── pages/          # View pages
│   └── Dockerfile.client   # Frontend container config
├── server/                 # Node.js backend
│   ├── controllers/        # Business logic
│   ├── middlewares/        # Auth, Rate limit, Sanitization
│   ├── models/             # Mongoose schemas
│   ├── routes/             # API endpoints
│   ├── utils/              # Email templates, Zod schemas
│   └── Dockerfile.server   # Backend container config
├── images/                 # Project assets
└── docker-compose.yml      # Multi-container orchestration

---

🔗 API Reference

Method	Endpoint	Description	Auth Required
POST	/api/auth/register	Register new user	❌
POST	/api/auth/login	User login	❌
POST	/api/auth/logout	User logout	❌
POST	/api/auth/send-verify-otp	Send verification OTP	✅
POST	/api/auth/verify-account	Verify account with OTP	✅
GET	/api/auth/is-auth	Check auth status	✅
POST	/api/auth/send-reset-otp	Send password reset OTP	❌
POST	/api/auth/reset-password	Reset password with OTP	❌

---

🧹 Maintenance Scripts

Located in server/testScripts/:

• clearUsers.js: Wipe the users collection.
• testMail.js: Verify SMTP configuration.