Cloud-native MEAN boilerplate

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

.env.example

@@ -0,0 +1,21 @@
+# ==============================================
+# MEAN Cloud-Native Boilerplate — Environment
+# ==============================================
+# Copy this file to `.env` and fill in real values.
+
+# --- MongoDB ---
+MONGO_PORT=27017
+MONGO_USERNAME=admin
+MONGO_PASSWORD=password
+MONGO_DATABASE=mean_app
+
+# --- Backend ---
+BACKEND_PORT=3000
+NODE_ENV=development
+JWT_SECRET=change-me-to-a-random-string
+JWT_EXPIRATION=1h
+CORS_ORIGIN=http://localhost:4200
+LOG_LEVEL=debug
+
+# --- Frontend ---
+FRONTEND_PORT=4200

.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI Pipeline
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION: '20'
+
+jobs:
+  backend:
+    name: Backend — Lint, Test & Build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: backend
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: backend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+  frontend:
+    name: Frontend — Build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npx ng build --configuration production
+
+  docker:
+    name: Docker Build Verification
+    runs-on: ubuntu-latest
+    needs: [backend, frontend]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build backend Docker image
+        run: docker build --target production -t mean-backend:ci ./backend
+
+      - name: Build frontend Docker image
+        run: docker build --target production -t mean-frontend:ci ./frontend

.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+dist/
+build/
+coverage/
+.env
+.env.local
+*.log
+.DS_Store
+.angular/
+.vscode/
+*.tgz
+.nyc_output/
+tmp/

.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit $1

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+build
+coverage
+.angular
+.next

.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "endOfLine": "lf",
+  "arrowParens": "always",
+  "bracketSpacing": true
+}

README.md

@@ -1 +1,138 @@
-# mean-boilerplate
+# Cloud-Native MEAN Stack Boilerplate
+
+A production-ready, cloud-native MEAN (MongoDB, Express.js, Angular, Node.js) boilerplate built with **TypeScript** and following the **12-Factor App** methodology.
+
+## Tech Stack
+
+| Layer      | Technology                                     |
+| ---------- | ---------------------------------------------- |
+| Database   | MongoDB 7 + Mongoose ODM                       |
+| Backend    | Node.js 20+ / Express.js / TypeScript (Strict) |
+| Frontend   | Angular 19 / Standalone Components / Signals   |
+| Containers | Docker multi-stage builds / Docker Compose     |
+| CI/CD      | GitHub Actions                                 |
+
+## Project Structure
+
+```
+├── backend/
+│   ├── src/
+│   │   ├── config/          # Env validation (Zod), DB connection
+│   │   ├── middleware/       # Error handler, validation, not-found
+│   │   ├── modules/
+│   │   │   ├── auth/        # JWT auth (register, login, middleware)
+│   │   │   ├── health/      # Liveness & readiness probes
+│   │   │   └── users/       # CRUD user management
+│   │   ├── utils/           # Logger (Pino), AppError, response helpers
+│   │   ├── app.ts           # Express app factory
+│   │   └── server.ts        # Bootstrap & graceful shutdown
+│   ├── tests/               # Jest unit & integration tests
+│   └── Dockerfile           # Multi-stage (dev + prod)
+├── frontend/
+│   ├── src/
+│   │   ├── app/
+│   │   │   ├── core/        # Auth service, interceptors, guards
+│   │   │   ├── features/    # Home, Auth (login/register), Dashboard
+│   │   │   └── shared/      # Models, shared components
+│   │   ├── environments/    # Dev & prod environment configs
+│   │   └── styles/          # Global SCSS
+│   ├── nginx.conf           # Production Nginx config
+│   └── Dockerfile           # Multi-stage (dev + Nginx prod)
+├── .github/workflows/ci.yml # CI pipeline
+├── docker-compose.yml       # Full stack local development
+└── .husky/                  # Git hooks (commitlint, lint-staged)
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >= 20
+- Docker & Docker Compose
+- npm >= 10
+
+### Development with Docker (Recommended)
+
+```bash
+cp .env.example .env
+docker compose up --build
+```
+
+| Service  | URL                       |
+| -------- | ------------------------- |
+| Frontend | http://localhost:4200     |
+| Backend  | http://localhost:3000     |
+| MongoDB  | mongodb://localhost:27017 |
+
+### Local Development (without Docker)
+
+```bash
+# Install all dependencies
+npm install
+
+# Start backend (requires MongoDB running)
+npm run dev:backend
+
+# Start frontend (in another terminal)
+npm run dev:frontend
+```
+
+## API Endpoints
+
+### Health Checks
+
+| Method | Endpoint            | Description                          |
+| ------ | ------------------- | ------------------------------------ |
+| GET    | `/health/liveness`  | Process is running                   |
+| GET    | `/health/readiness` | App can serve traffic (DB connected) |
+
+### Auth
+
+| Method | Endpoint             | Description       |
+| ------ | -------------------- | ----------------- |
+| POST   | `/api/auth/register` | Register new user |
+| POST   | `/api/auth/login`    | Login             |
+| GET    | `/api/auth/profile`  | Get current user  |
+
+### Users (Authenticated)
+
+| Method | Endpoint         | Description        |
+| ------ | ---------------- | ------------------ |
+| GET    | `/api/users`     | List users (paged) |
+| GET    | `/api/users/:id` | Get user by ID     |
+| PATCH  | `/api/users/:id` | Update user        |
+| DELETE | `/api/users/:id` | Soft-delete user   |
+
+## Testing
+
+```bash
+# Backend tests
+cd backend && npm test
+
+# Frontend tests (requires Chrome/Chromium)
+cd frontend && npm test
+```
+
+## Code Quality
+
+- **ESLint** + **Prettier** for consistent formatting
+- **Husky** pre-commit hooks run lint-staged
+- **Commitlint** enforces Conventional Commits (`feat:`, `fix:`, etc.)
+- **TypeScript Strict Mode** across the entire stack
+
+## Security
+
+- **Helmet** for HTTP security headers
+- **CORS** configured per environment
+- **Rate limiting** on API routes (100 req / 15 min)
+- **bcrypt** password hashing (12 salt rounds)
+- **JWT** bearer token authentication
+- **Zod** request validation
+
+## Environment Variables
+
+See `.env.example` for all configuration options. The backend validates all required environment variables at startup using Zod — the server will refuse to start with invalid config.
+
+## License
+
+MIT

backend/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+coverage
+.env
+.env.local
+*.log
+.git

backend/.env.example

@@ -0,0 +1,18 @@
+# ==============================================
+# Backend Environment Variables
+# ==============================================
+NODE_ENV=development
+PORT=3000
+
+# --- MongoDB ---
+MONGO_URI=mongodb://admin:password@localhost:27017/mean_app?authSource=admin
+
+# --- JWT ---
+JWT_SECRET=change-me-to-a-random-string
+JWT_EXPIRATION=1h
+
+# --- CORS ---
+CORS_ORIGIN=http://localhost:4200
+
+# --- Logging ---
+LOG_LEVEL=debug

backend/Dockerfile

@@ -0,0 +1,45 @@
+# ============================================
+# Stage 1: Base image with dependencies
+# ============================================
+FROM node:20-alpine AS base
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci --ignore-scripts
+COPY . .
+
+# ============================================
+# Stage 2: Development (hot-reload with tsx)
+# ============================================
+FROM base AS development
+ENV NODE_ENV=development
+EXPOSE 3000
+CMD ["npm", "run", "dev"]
+
+# ============================================
+# Stage 3: Build the TypeScript source
+# ============================================
+FROM base AS build
+RUN npm run build
+
+# ============================================
+# Stage 4: Production-optimized image
+# ============================================
+FROM node:20-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+
+RUN addgroup -g 1001 -S appgroup && \
+    adduser -S appuser -u 1001 -G appgroup
+
+COPY package.json package-lock.json* ./
+RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
+
+COPY --from=build /app/dist ./dist
+
+USER appuser
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget --quiet --tries=1 --spider http://localhost:3000/health/liveness || exit 1
+
+CMD ["node", "dist/server.js"]