{"id":29202057,"url":"https://github.com/sinanptm/clean-auth-template","last_synced_at":"2026-04-04T20:33:16.244Z","repository":{"id":342862769,"uuid":"989361865","full_name":"sinanptm/clean-auth-template","owner":"sinanptm","description":"Full-stack clean architecture, authentication template with Next.js, NodeJs, TypeScript. Features email/OTP, OAuth, RBAC, JWT security, and clean architecture for easy customization and scaling.","archived":false,"fork":false,"pushed_at":"2025-09-29T17:17:33.000Z","size":1152,"stargazers_count":53,"open_issues_count":0,"forks_count":8,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-07T23:51:23.062Z","etag":null,"topics":["auth-template","clean-architecture","clean-code","expressjs","jwt","mongodb","nextjs15","nodejs","open-source","shadcn","tyepscript"],"latest_commit_sha":null,"homepage":"https://clean-auth-template.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sinanptm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-24T00:20:05.000Z","updated_at":"2026-02-21T15:13:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sinanptm/clean-auth-template","commit_stats":null,"previous_names":["sinanptm/clean-auth-template"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/sinanptm/clean-auth-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinanptm%2Fclean-auth-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinanptm%2Fclean-auth-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinanptm%2Fclean-auth-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinanptm%2Fclean-auth-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sinanptm","download_url":"https://codeload.github.com/sinanptm/clean-auth-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinanptm%2Fclean-auth-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31413269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth-template","clean-architecture","clean-code","expressjs","jwt","mongodb","nextjs15","nodejs","open-source","shadcn","tyepscript"],"created_at":"2025-07-02T13:00:34.159Z","updated_at":"2026-04-04T20:33:16.234Z","avatar_url":"https://github.com/sinanptm.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Full-Stack Authentication Template\n\n**A production-ready authentication system built with clean architecture principles and modern technologies**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Downloads](https://img.shields.io/npm/dm/clean-auth.svg)](https://www.npmjs.com/package/clean-auth)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n\n\u003c/div\u003e\n\n---\n\n## 📖 Overview\n\nThis 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.\n\n**📚 Documentation**: [https://clean-auth-template.vercel.app](https://clean-auth-template.vercel.app/) \u003cbr /\u003e\n**🛠️ CLI Tool**: [https://npmjs.com/package/clean-auth](https://www.npmjs.com/package/clean-auth)\n\n\u003cimg src=\"https://github.com/user-attachments/assets/efdc2095-d663-4b66-bea9-33a1190c302b\" alt=\"Application Preview Dark\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/487c4a48-c394-499f-b21f-eefec2250496\" alt=\"Application Preview Light\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\nThe 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.\n\n---\n\n## 🚀 Quick Start with CLI\n\nThe fastest way to get started is using our CLI tool:\n\n**Install the CLI**\n\n```bash\nnpm install -g clean-auth\n```\n\n**Create a New Project**\n\n```bash\n# OR Use npx (Without Installing Globally)\n# Run commands without installing the CLI globally\nnpx clean-auth init my-auth-project --i\ncd my-auth-project\n```\n\n**Configure Authentication**\n\n```bash\nclean-auth config [options]\n```\n\n**Start Development**\n\n```bash\npnpm dev\n```\n\n### Alternative\n\nIf you prefer to set up the project manually without using CLI:\n\n**Clone the repository**\n\n```bash\ngit clone https://github.com/sinanptm/fullstack-clean-auth-template.git\ncd fullstack-clean-auth-template\n```\n\n**Install dependencies**\n\n```bash\npnpm install\n```\n\n**Start Development**\n\n```bash\npnpm dev\n```\n\n---\n\n## 💻 Prerequisites\n\n- Node.js v20 or higher\n- pnpm v10.8.1 or higher\n- MongoDB (local installation or MongoDB Atlas)\n- Firebase project with Authentication enabled\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\n🛠️ CLI Commands\n\u003c/strong\u003e\u003c/summary\u003e\n\nThe **clean-auth** CLI provides powerful commands to scaffold and manage your authentication project:\n\n### `init` - Initialize Project\n\nCreate a new full-stack authentication project with clean architecture.\n\n```bash\nclean-auth init \u003cproject-name\u003e [options]\n```\n\n**Options:**\n\n- `-i, --install` - Automatically install dependencies after project creation\n\n**Examples:**\n\n```bash\nclean-auth init my-auth-project\nclean-auth init my-auth-project --install\n```\n\n### `config` - Configure Authentication\n\nSet up environment variables and authentication configuration interactively.\n\n```bash\nclean-auth config [options]\n```\n\n**Options:**\n\n- `-s, --skip` - Skip interactive prompts and use default values\n\n**Examples:**\n\n```bash\nclean-auth config\nclean-auth config --skip\n```\n\n### `clean` - Clean Project Structure\n\nRemove unnecessary parts of your project structure to customize it for your needs.\n\n```bash\nclean-auth clean [options]\n```\n\n**Options:**\n\n- `-s, --server` - Remove entire server directory and update root configurations\n- `-w, --web` - Remove entire web directory and update root configurations\n- `-o, --opensource` - Remove open source files (LICENSE, CONTRIBUTING.md, README.md)\n\n**Examples:**\n\n```bash\nclean-auth clean --server\nclean-auth clean --web --opensource\n```\n\n### `help` - Show All Commands\n\nDisplay a list of all available commands.\n\n```bash\nclean-auth help\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\n📱 Application Screenshots\n\u003c/strong\u003e\u003c/summary\u003e\n    \n### Authentication Flow\n\u003cdiv style=\"display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 20px; margin: 20px 0;\"\u003e\n\n**User Registration**\n\u003cimg src=\"https://github.com/user-attachments/assets/c2178cd3-0e27-480d-8bb9-997a1f42d2da\" alt=\"User Signup Page\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\n**Forgot Password Modal**\n\u003cimg src=\"https://github.com/user-attachments/assets/c427b1fd-53d6-4cff-a5c3-9633e3056716\" alt=\"Forgot Password Popup\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\n**Password Reset Email**\n\u003cimg src=\"https://github.com/user-attachments/assets/b41320de-8cb2-4e5d-930b-061cfc608b1b\" alt=\"Forgot Password Email\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\n**OTP Verification**\n\u003cimg src=\"https://github.com/user-attachments/assets/31797b3a-6ead-4d2c-a23a-549e907da59f\" alt=\"OTP Verification Page\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\n**OTP Email Verification**\n\u003cimg src=\"https://github.com/user-attachments/assets/af435d9a-9c70-4083-948d-2927fb7e87ac\" alt=\"OTP Verification Email\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\n\u003c/div\u003e\n\n### User \u0026 Admin Interfaces\n\n\u003cdiv style=\"display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 20px; margin: 20px 0;\"\u003e\n\n**User Profile Dashboard**\n\u003cimg src=\"https://github.com/user-attachments/assets/3c8aa0bb-f406-4e9a-8efa-eeda59fffbbc\" alt=\"User Profile Page\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\n**Admin Login**\n\u003cimg src=\"https://github.com/user-attachments/assets/793bd7a9-5b01-4285-bbe0-a644fa6dffdb\" alt=\"Admin Signin Page\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\n**Admin Dashboard**\n\u003cimg src=\"https://github.com/user-attachments/assets/c2e5edef-db7d-488b-8c2e-9c7c1d331f69\" alt=\"Admin Dashboard\" width=\"100%\" style=\"border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);\" /\u003e\n\n\u003c/div\u003e\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e✨ Key Features\u003c/strong\u003e\u003c/summary\u003e\n\n### 🏗️ Architecture \u0026 Design\n\n- **Clean Architecture** - Domain-driven design with clear separation of concerns\n- **Modular Structure** - Easy to extend and maintain\n- **Framework Independence** - Core business logic is decoupled from frameworks\n- **TypeScript First** - Full type safety across the entire stack\n\n### 🔐 Authentication \u0026 Security\n\n- **Multi-factor Authentication** - Email/Password with OTP verification\n- **OAuth Integration** - Google and GitHub social login\n- **Role-based Access Control** - User and admin roles with protected routes\n- **JWT Token Management** - Secure access and refresh token implementation\n- **Security Best Practices** - Rate limiting, CORS, bcrypt hashing\n\n### ⚡ Modern Technology Stack\n\n- **Frontend**: Next.js 15, React 19, Tailwind CSS, Shadcn UI\n- **Backend**: Express.js 5, Node.js, TypeScript\n- **Database**: MongoDB with Mongoose ODM\n- **State Management**: Zustand + React Query\n- **Authentication**: Firebase OAuth, JWT, Nodemailer\n\n### 🚀 Production Ready\n\n- **Scalable Architecture** - Built for enterprise-level applications\n- **Comprehensive Testing** - Unit and integration tests included\n- **Development Tools** - ESLint, Prettier, Hot reload\n- **Deployment Ready** - Production-optimized builds\n- **CI/CD Pipeline** - Automated testing, building, and quality checks\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\n🔧 CI/CD Pipeline\n\u003c/strong\u003e\u003c/summary\u003e\n\n### 🔄 Automated Workflows\n\n- **Continuous Integration** - Automated testing and building on every push\n- **Quality Assurance** - Code formatting, linting, and type checking\n- **Security Auditing** - Weekly dependency vulnerability scans\n- **Dependency Management** - Automated dependency updates with PR creation\n\n### GitHub Actions Workflows\n\n| Workflow                | Trigger                       | Purpose                         |\n| ----------------------- | ----------------------------- | ------------------------------- |\n| **CI/CD Pipeline**      | Push to `main`/`develop`, PRs | Build, test, and quality checks |\n| **Security Audit**      | Weekly schedule, Push/PR      | Vulnerability scanning          |\n| **Update Dependencies** | Weekly schedule, Manual       | Automated dependency updates    |\n\n#### Pipeline Features\n\n- **Parallel Execution** - Server and web builds run simultaneously\n- **Caching Strategy** - Optimized build times with dependency caching\n- **Artifact Management** - Build artifacts stored for deployment\n- **Multi-stage Validation** - Tests, linting, and type checking\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📚 API Documentation\u003c/strong\u003e\u003c/summary\u003e\n\n| Method | Endpoint                    | Description             | Body                          |\n| ------ | --------------------------- | ----------------------- | ----------------------------- |\n| `POST` | `/api/auth/signup`          | User registration       | `{ email, password, name }`   |\n| `POST` | `/api/auth/signin`          | Email/password login    | `{ email, password }`         |\n| `POST` | `/api/auth/verify-otp`      | Verify OTP code         | `{ email, otp }`              |\n| `POST` | `/api/auth/oauth-2`         | OAuth authentication    | `{ firebaseToken }`           |\n| `POST` | `/api/auth/forgot-password` | Request password reset  | `{ email }`                   |\n| `POST` | `/api/auth/reset-password`  | Reset password with OTP | `{ email, otp, newPassword }` |\n| `POST` | `/api/auth/refresh`         | Refresh access token    | `{ refreshToken }`            |\n| `POST` | `/api/auth/logout`          | User logout             | -                             |\n\n**👤 User Endpoints**\n\n| Method | Endpoint            | Description         | Auth Required |\n| ------ | ------------------- | ------------------- | ------------- |\n| `GET`  | `/api/user/profile` | Get user profile    | ✅ User       |\n| `PUT`  | `/api/user/profile` | Update user profile | ✅ User       |\n\n**👑 Admin Endpoints**\n\n| Method   | Endpoint               | Description       | Auth Required |\n| -------- | ---------------------- | ----------------- | ------------- |\n| `POST`   | `/api/admin/signin`    | Admin login       | -             |\n| `GET`    | `/api/admin/users`     | List all users    | ✅ Admin      |\n| `GET`    | `/api/admin/users/:id` | Get specific user | ✅ Admin      |\n| `PUT`    | `/api/admin/users/:id` | Update user       | ✅ Admin      |\n| `DELETE` | `/api/admin/users/:id` | Delete user       | ✅ Admin      |\n| `GET`    | `/api/admin/analytics` | System analytics  | ✅ Admin      |\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔒 Security Features\u003c/strong\u003e\u003c/summary\u003e\n\n### 🔐 Authentication Security\n\n- **JWT Tokens**: Secure access and refresh token implementation\n- **HTTP-Only Cookies**: Protection against XSS attacks\n- **Password Hashing**: bcrypt with 10 salt rounds\n- **OTP Verification**: Time-limited one-time passwords\n\n### 🛡️ Authorization \u0026 Access Control\n\n- **Role-Based Access Control (RBAC)**: User and admin roles\n- **Protected Routes**: Middleware-based route protection\n- **Token Validation**: Server-side Firebase token verification\n\n### 🚫 Attack Prevention\n\n- **Rate Limiting**: Request throttling to prevent abuse\n- **CORS Configuration**: Cross-origin request security\n- **Input Validation**: Comprehensive Joi schema validation\n- **SQL Injection Prevention**: Parameterized database queries\n\n### 🔍 Monitoring \u0026 Logging\n\n- **Request Logging**: Detailed API request logging\n- **Error Tracking**: Comprehensive error handling\n- **Security Headers**: Helmet.js security headers\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\n    🔄 Authentication Flow Diagram\n\u003c/strong\u003e\u003c/summary\u003e\n\n```mermaid\ngraph TB\n    %% Entry Point\n    A[\"🔑 Sign In/Up Page\"] --\u003e B{\"Authentication Method\"}\n\n    %% Email/Password Flow\n    B --\u003e|\"📧 Email/Password\"| C[\"📝 Enter Credentials\"]\n    C --\u003e D{\"Valid Credentials?\"}\n    D --\u003e|\"❌\"| E[\"❌ Error Message\"]\n    E --\u003e C\n    D --\u003e|\"✅\"| F[\"🔢 Generate OTP\"]\n    F --\u003e G[\"📧 Send OTP Email\"]\n    G --\u003e H[\"🔢 OTP Verification Page\"]\n    H --\u003e I[\"Enter OTP Code\"]\n    I --\u003e J{\"Valid \u0026 Fresh OTP?\"}\n    J --\u003e|\"❌\"| K[\"Try Again\"]\n    K --\u003e I\n    J --\u003e|\"✅\"| L[\"🎯 Generate JWT\"]\n\n    %% OAuth Flow\n    B --\u003e|\"🔥 OAuth (Google/GitHub)\"| M[\"🔥 Firebase OAuth Popup\"]\n    M --\u003e N[\"👤 Select Provider\"]\n    N --\u003e O[\"🔐 Provider Authentication\"]\n    O --\u003e P{\"Auth Success?\"}\n    P --\u003e|\"❌\"| Q[\"❌ OAuth Error\"]\n    Q --\u003e A\n    P --\u003e|\"✅\"| R[\"🎯 Get Firebase Token\"]\n    R --\u003e S[\"📧 Extract User Info\"]\n    S --\u003e T[\"🔗 Send Token to Backend\"]\n    T --\u003e U[\"🔍 Validate Firebase Token\"]\n    U --\u003e V{\"Token Valid?\"}\n    V --\u003e|\"❌\"| W[\"❌ Token Invalid\"]\n    W --\u003e A\n    V --\u003e|\"✅\"| X{\"User Exists?\"}\n    X --\u003e|\"❌\"| Y[\"👤 Create New User\"]\n    X --\u003e|\"✅\"| Z[\"📝 Update User Info\"]\n    Y --\u003e L\n    Z --\u003e L\n\n    %% Common Final Steps\n    L --\u003e AA[\"🍪 Set HTTP-Only Cookies\"]\n    AA --\u003e BB[\"✨ Authenticated User\"]\n    BB --\u003e CC[\"🛡️ User Dashboard Access\"]\n\n    %% Additional Flows\n    DD[\"🔄 Token Expiry\"] --\u003e EE[\"🔄 Auto Refresh\"]\n    EE --\u003e BB\n\n    FF[\"🔒 Forgot Password\"] --\u003e GG[\"📧 Reset Email with OTP\"]\n    GG --\u003e HH[\"🔢 OTP Verification\"]\n    HH --\u003e II[\"🔑 New Password\"]\n    II --\u003e A\n\n    %% Admin Flow (Separate)\n    JJ[\"🔒 Admin Login\"] --\u003e KK[\"📧 Admin Credentials\"]\n    KK --\u003e LL[\"🔍 Validate with .env\"]\n    LL --\u003e MM{\"Match Admin Config?\"}\n    MM --\u003e|\"❌\"| NN[\"❌ Access Denied\"]\n    NN --\u003e JJ\n    MM --\u003e|\"✅\"| OO[\"🎯 Generate Admin JWT\"]\n    OO --\u003e PP[\"🏷️ Set Admin Role\"]\n    PP --\u003e QQ[\"🍪 Set Admin Cookies\"]\n    QQ --\u003e RR[\"✨ Authenticated Admin\"]\n    RR --\u003e SS[\"👑 Admin Panel Access\"]\n```\n\n\u003c/details\u003e\n\n---\n\n## 💻 Development\n\n### Available Scripts\n\n#### Root Level\n\n```bash\npnpm dev          # Start both frontend and backend\npnpm format       # Format code using Prettier\npnpm lint         # Lint entire project\n```\n\n#### Backend (`server/`)\n\n```bash\npnpm dev          # Start development server with hot reload\npnpm build        # Build for production\npnpm start        # Start production server\npnpm test         # Run test suite\n```\n\n#### Frontend (`web/`)\n\n```bash\npnpm dev          # Start Next.js development server\npnpm build        # Build for production\npnpm start        # Start production server\npnpm lint         # Lint frontend code\n```\n\n---\n\n# 🤝 Contributing\n\n[Contributing Guidelines](CONTRIBUTING.md)\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE) – see the LICENSE file for details.\n\n\u003cdiv align=\"center\"\u003e\n\n### ⭐ Star this repository if it helped you!\n\n[![GitHub stars](https://img.shields.io/github/stars/sinanptm/fullstack-clean-auth-template?style=social)](https://github.com/sinanptm/fullstack-clean-auth-template)\n\n**Built with ❤️ for the developer community**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinanptm%2Fclean-auth-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsinanptm%2Fclean-auth-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinanptm%2Fclean-auth-template/lists"}