Apex MEAN Stack Boilerplate

A production-ready, high-performance monorepo boilerplate built with MongoDB, Express, Angular 21 (Standalone Components & Signals), and Node.js. It features a complete JWT authentication flow with silent token rotation using secure HttpOnly cookies, structural route protection, responsive UI with Tailwind CSS v4, integration tests, dynamic API docs, and Docker orchestration.

---

🛠️ Technology Stack

• Frontend: Angular 21 (Standalone Components, Signals State, functional Route Guards & Interceptors)
• Backend: Node.js + Express (ESModules, modular routing, clean middlewares)
• Database: MongoDB + Mongoose (automatic reconnection, Schema validation)
• Security: Helmet, CORS origin whitelist, Express Rate Limit, NoSQL Mongo Sanitize, XSS filters, secure cookies
• Styling: Tailwind CSS v4 + PostCSS with modern glassmorphism UI variables
• Testing: Jest + Supertest (Backend), Vitest (Frontend)
• DevOps: Docker, Docker Compose, GitHub Actions CI, Husky + lint-staged

---

📂 Project Structure

├── .github/workflows/ci.yml # Automated CI pipeline (Linter & Tests)
├── client/                  # Frontend Angular Application
│   ├── src/
│   │   ├── app/
│   │   │   ├── core/        # AuthService, ProductService, guards, interceptors, models
│   │   │   ├── shared/      # Reusable components (Button, Input, Card, Modal, Spinner, Toast)
│   │   │   ├── features/    # Page components: Home, Login, Register, Dashboard, Profile, NotFound
│   │   │   ├── app.config.ts# Global providers (HttpInterceptors, Routing)
│   │   │   └── app.routes.ts# Standalone route declarations with lazy loading
│   │   └── styles.css       # Tailwind CSS v4 stylesheet imports and custom themes
│   ├── Dockerfile           # Multi-stage production container build (Node -> Nginx)
│   ├── nginx.conf           # Nginx reverse proxy configuration supporting SPA deep-links
│   └── package.json
├── server/                  # Backend Node/Express API
│   ├── src/
│   │   ├── config/          # DB connection, configuration validation via Joi
│   │   ├── models/          # User & Product Mongoose schemas
│   │   ├── controllers/     # Authentication & Product CRUD controllers
│   │   ├── routes/          # API endpoint routers annotated with Swagger
│   │   ├── middlewares/     # Auth, roles, Joi validation, global error handlers
│   │   ├── utils/           # Custom operational Errors, Winston logger setup
│   │   ├── app.js           # Express instance config, security headers, rate limits
│   │   └── server.js        # Main startup script
│   ├── tests/               # Backend integration tests (Supertest + Jest)
│   ├── Dockerfile           # Backend NodeJS production container configuration
│   ├── jest.config.js       # Jest testing options
│   └── package.json
├── docker-compose.yml       # Dev workspace composer (MongoDB, server, client + hot-reload)
├── .gitignore
├── package.json             # Monorepo task workspace manager
└── README.md

---

🔑 Environment Variables

The backend relies on the configuration variables declared in /server/.env. A template is provided in server/.env.example:

Variable	Description	Default
NODE_ENV	Mode of operation (development / production / test)	development
PORT	Port number for Express server	5000
MONGO_URI	MongoDB Connection URL	mongodb://localhost:27017/apex-mean
JWT_ACCESS_SECRET	Secret key for access token signing	(Required)
JWT_REFRESH_SECRET	Secret key for refresh token signing	(Required)
JWT_ACCESS_EXPIRATION	Access token duration	15m
JWT_REFRESH_EXPIRATION	Refresh token duration	7d
CORS_ORIGIN	Whitelisted origin for client CORS requests	http://localhost:4200

---

🚀 Getting Started

Prerequisites

Make sure you have the following installed:

• Node.js (v20+ recommended)
• MongoDB (if running locally without Docker)
• Docker & Docker Compose (optional)

---

Method A: Local Development Setup

1. Clone the repository and navigate to the project directory:

   cd mean-stack-boilerplate

2. Install all dependencies (installs root, client, and server dependencies):

   npm run install:all

3. Configure Environment Variables: Copy .env.example in the server directory to .env (the defaults are pre-configured for a local setup):

   cp server/.env.example server/.env

4. Start MongoDB locally on localhost:27017.

5. Start Dev Servers (concurrently launches Express on port 5000 and Angular on port 4200):

   npm run dev

6. Open your browser:

   • Frontend App: http://localhost:4200
   • Swagger API Explorer: http://localhost:5000/api-docs
   • API Health Check: http://localhost:5000/api/health

---

Method B: Docker Compose Setup (One-Click)

Docker Compose automatically spins up MongoDB, the Express backend, and the Angular frontend, configuring volumes for local code hot-reload.

1. Configure Environment Variables: Ensure you have server/.env configured. Note that inside the docker-compose network, the server must reference MongoDB as mongodb host instead of localhost:

   MONGO_URI=mongodb://mongodb:27017/apex-mean

2. Launch Containers:

   docker compose up --build

3. Open your browser:

   • Frontend App: http://localhost:4200
   • Swagger API Explorer: http://localhost:5000/api-docs

---

🧪 Running Tests & Audits

1. Integration Tests (Backend)

Tests run on a separate environment using Supertest + Jest, ensuring schemas, authentication barriers, and product CRUD work properly:

# Run backend tests
npm run test

2. Frontend Tests (Client)

Uses Vitest setup via @angular/build:unit-test configuration:

# Run client tests
npm run test:client

3. Code Quality (ESLint + Prettier)

Runs linters over the client and server codebases:

# Lint entire repository
npm run lint