Full-Stack Authentication Template

A production-ready authentication system built with clean architecture principles and modern technologies

---

📖 Overview

This comprehensive full-stack authentication template is designed with clean architecture principles, providing a solid foundation for building scalable web applications with robust user authentication and authorization systems.

📚 Documentation: https://clean-auth-template.vercel.app 🛠️ CLI Tool: https://npmjs.com/package/clean-auth

The template demonstrates modern web development practices with a focus on security, scalability, and maintainability. It includes comprehensive authentication flows, role-based access control, and production-ready deployment configurations.

---

🚀 Quick Start with CLI

The fastest way to get started is using our CLI tool:

Install the CLI

npm install -g clean-auth

Create a New Project

# OR Use npx (Without Installing Globally)
# Run commands without installing the CLI globally
npx clean-auth init my-auth-project --i
cd my-auth-project

Configure Authentication

clean-auth config [options]

Start Development

pnpm dev

Alternative

If you prefer to set up the project manually without using CLI:

Clone the repository

git clone https://github.com/sinanptm/fullstack-clean-auth-template.git
cd fullstack-clean-auth-template

Install dependencies

pnpm install

Start Development

pnpm dev

---

💻 Prerequisites

• Node.js v20 or higher
• pnpm v10.8.1 or higher
• MongoDB (local installation or MongoDB Atlas)
• Firebase project with Authentication enabled

---

The clean-auth CLI provides powerful commands to scaffold and manage your authentication project:

init - Initialize Project

Create a new full-stack authentication project with clean architecture.

clean-auth init <project-name> [options]

Options:

• -i, --install - Automatically install dependencies after project creation

Examples:

clean-auth init my-auth-project
clean-auth init my-auth-project --install

config - Configure Authentication

Set up environment variables and authentication configuration interactively.

clean-auth config [options]

Options:

• -s, --skip - Skip interactive prompts and use default values

Examples:

clean-auth config
clean-auth config --skip

clean - Clean Project Structure

Remove unnecessary parts of your project structure to customize it for your needs.

clean-auth clean [options]

Options:

• -s, --server - Remove entire server directory and update root configurations
• -w, --web - Remove entire web directory and update root configurations
• -o, --opensource - Remove open source files (LICENSE, CONTRIBUTING.md, README.md)

Examples:

clean-auth clean --server
clean-auth clean --web --opensource

help - Show All Commands

Display a list of all available commands.

clean-auth help

---

Authentication Flow

User Registration

Forgot Password Modal

Password Reset Email

OTP Verification

OTP Email Verification

User & Admin Interfaces

User Profile Dashboard

Admin Login

Admin Dashboard

---

🏗️ Architecture & Design

• Clean Architecture - Domain-driven design with clear separation of concerns
• Modular Structure - Easy to extend and maintain
• Framework Independence - Core business logic is decoupled from frameworks
• TypeScript First - Full type safety across the entire stack

🔐 Authentication & Security

• Multi-factor Authentication - Email/Password with OTP verification
• OAuth Integration - Google and GitHub social login
• Role-based Access Control - User and admin roles with protected routes
• JWT Token Management - Secure access and refresh token implementation
• Security Best Practices - Rate limiting, CORS, bcrypt hashing

⚡ Modern Technology Stack

• Frontend: Next.js 15, React 19, Tailwind CSS, Shadcn UI
• Backend: Express.js 5, Node.js, TypeScript
• Database: MongoDB with Mongoose ODM
• State Management: Zustand + React Query
• Authentication: Firebase OAuth, JWT, Nodemailer

🚀 Production Ready

• Scalable Architecture - Built for enterprise-level applications
• Comprehensive Testing - Unit and integration tests included
• Development Tools - ESLint, Prettier, Hot reload
• Deployment Ready - Production-optimized builds
• CI/CD Pipeline - Automated testing, building, and quality checks

---

🔄 Automated Workflows

• Continuous Integration - Automated testing and building on every push
• Quality Assurance - Code formatting, linting, and type checking
• Security Auditing - Weekly dependency vulnerability scans
• Dependency Management - Automated dependency updates with PR creation

GitHub Actions Workflows

Workflow	Trigger	Purpose
CI/CD Pipeline	Push to main/develop, PRs	Build, test, and quality checks
Security Audit	Weekly schedule, Push/PR	Vulnerability scanning
Update Dependencies	Weekly schedule, Manual	Automated dependency updates

Pipeline Features

• Parallel Execution - Server and web builds run simultaneously
• Caching Strategy - Optimized build times with dependency caching
• Artifact Management - Build artifacts stored for deployment
• Multi-stage Validation - Tests, linting, and type checking

---

Method	Endpoint	Description	Body
POST	/api/auth/signup	User registration	{ email, password, name }
POST	/api/auth/signin	Email/password login	{ email, password }
POST	/api/auth/verify-otp	Verify OTP code	{ email, otp }
POST	/api/auth/oauth-2	OAuth authentication	{ firebaseToken }
POST	/api/auth/forgot-password	Request password reset	{ email }
POST	/api/auth/reset-password	Reset password with OTP	{ email, otp, newPassword }
POST	/api/auth/refresh	Refresh access token	{ refreshToken }
POST	/api/auth/logout	User logout	-

👤 User Endpoints

Method	Endpoint	Description	Auth Required
GET	/api/user/profile	Get user profile	✅ User
PUT	/api/user/profile	Update user profile	✅ User

👑 Admin Endpoints

Method	Endpoint	Description	Auth Required
POST	/api/admin/signin	Admin login	-
GET	/api/admin/users	List all users	✅ Admin
GET	/api/admin/users/:id	Get specific user	✅ Admin
PUT	/api/admin/users/:id	Update user	✅ Admin
DELETE	/api/admin/users/:id	Delete user	✅ Admin
GET	/api/admin/analytics	System analytics	✅ Admin

---

🔐 Authentication Security

• JWT Tokens: Secure access and refresh token implementation
• HTTP-Only Cookies: Protection against XSS attacks
• Password Hashing: bcrypt with 10 salt rounds
• OTP Verification: Time-limited one-time passwords

🛡️ Authorization & Access Control

• Role-Based Access Control (RBAC): User and admin roles
• Protected Routes: Middleware-based route protection
• Token Validation: Server-side Firebase token verification

🚫 Attack Prevention

• Rate Limiting: Request throttling to prevent abuse
• CORS Configuration: Cross-origin request security
• Input Validation: Comprehensive Joi schema validation
• SQL Injection Prevention: Parameterized database queries

🔍 Monitoring & Logging

• Request Logging: Detailed API request logging
• Error Tracking: Comprehensive error handling
• Security Headers: Hel