🔐 Enterprise Auth Template

Production-ready authentication system built with Clean Architecture, DDD, and TypeScript. Framework-agnostic core that works with NestJS, Express, Fastify, and more.

✨ Why This Template?

Traditional auth systems couple business logic to frameworks, making them:

• ❌ Hard to test
• ❌ Impossible to reuse
• ❌ Difficult to maintain
• ❌ Framework-locked

This template solves all that:

• ✅ Framework Agnostic - Core works with ANY framework
• ✅ Production Ready - Used in real-world applications
• ✅ Fully Tested - 80%+ test coverage
• ✅ Enterprise Grade - Clean Architecture + DDD
• ✅ Type Safe - 100% TypeScript with strict mode
• ✅ Secure - Industry best practices built-in

🚀 Quick Start

# 1. Clone and install
git clone https://github.com/your-username/auth-template.git
cd auth-template
pnpm install

# 2. Setup environment
cp .env.example .env

# 3. Start infrastructure
docker-compose -f docker/development/docker-compose.yml up -d

# 4. Run application
pnpm run dev

# 5. Test API
curl http://localhost:3000/health

📦 What's Inside?

auth-template/
├── packages/
│   ├── core/              # 🎯 Framework-agnostic business logic
│   │   ├── domain/        # Entities, Value Objects, Repositories
│   │   ├── application/   # Use Cases, Ports, Services
│   │   └── shared/        # Events, Errors, Utilities
│   │
│   └── nestjs-adapter/    # 🔌 NestJS implementation
│       ├── infrastructure # TypeORM, Redis, Security
│       ├── presentation   # Controllers, Guards, DTOs
│       └── config         # Configuration
│
├── apps/
│   └── demo-api/          # 🎮 Example application
│
├── docs/                  # 📚 Complete documentation
├── tests/                 # 🧪 E2E & Integration tests
└── docker/                # 🐳 Docker configurations

🌟 Key Features

Security First

• ✅ JWT with token rotation
• ✅ Bcrypt/Argon2 password hashing
• ✅ Rate limiting & account lockout
• ✅ Email verification required
• ✅ Audit logging for all actions
• ✅ CORS & Helmet protection

Clean Architecture

• ✅ Zero framework dependencies in core
• ✅ Clear layer separation
• ✅ Easy to test every layer
• ✅ Dependency inversion principle
• ✅ Single responsibility principle

Developer Experience

• ✅ TypeScript with strict mode
• ✅ Result pattern (no exceptions)
• ✅ Comprehensive documentation
• ✅ Docker development environment
• ✅ Hot reload in development
• ✅ ESLint + Prettier configured

Production Ready

• ✅ Docker multi-stage builds
• ✅ CI/CD with GitHub Actions
• ✅ Health checks & monitoring
• ✅ Horizontal scaling ready
• ✅ Database connection pooling
• ✅ Multi-layer caching

📖 Documentation

• Getting Started - Setup in 5 minutes
• Architecture Overview - How it works
• Customization Guide - Add your features
• Deployment Guide - Go to production
• API Reference - OpenAPI 3.0 spec

Architecture Decision Records

• ADR 001: Clean Architecture
• ADR 002: Repository Pattern
• ADR 003: Event-Driven

🎯 Usage Examples

Basic Usage (NestJS)

import { AuthModule } from '@auth-template/nestjs-adapter';

@Module({
  imports: [
    AuthModule.forRoot({
      cacheProvider: 'redis',
      redisClient: new Redis(),
    }),
  ],
})
export class AppModule {}

Protect Routes

import { Public, CurrentUser, Roles } from '@auth-template/nestjs-adapter';
import { Role } from '@auth-template/core';

@Controller('products')
export class ProductsController {
  // Public route
  @Public()
  @Get()
  findAll() {
    return this.productsService.findAll();
  }

  // Protected route
  @Get('my')
  findMine(@CurrentUser('userId') userId: string) {
    return this.productsService.findByUser(userId);
  }

  // Role-based route
  @Post()
  @Roles(Role.ADMIN)
  create(@Body() dto: CreateProductDto) {
    return this.productsService.create(dto);
  }
}

Framework Agnostic Core

import { RegisterUser } from '@auth-template/core';

// Works with ANY framework (Express, Fastify, Koa, etc.)
const registerUser = new RegisterUser(
  userRepository,
  passwordHasher,
  tokenGenerator,
  emailSender,
  eventBus,
  logger,
);

const result = await registerUser.execute({
  email: 'user@example.com',
  password: 'SecurePass@123',
});

if (result.isSuccess) {
  const { userId, accessToken } = result.getValue();
}

🧪 Testing

# Unit tests
pnpm test

# E2E tests
pnpm test:e2e

# Coverage
pnpm test:cov

# Watch mode
pnpm test:watch

🐳 Docker

# Development
docker-compose -f docker/development/docker-compose.yml up

# Production
docker-compose -f docker/production/docker-compose.prod.yml up -d

# Build
docker build -t auth-template:latest -f docker/Dockerfile .

📊 Performance

Operation	Time	RPS
Register	120ms	833
Login	110ms	909
Refresh	25ms	4000
Protected Route	15ms	6666

🛠️ Tech Stack

• Core: TypeScript, UUID
• Framework: NestJS (adapter included)
• Database: TypeORM with PostgreSQL
• Cache: Redis / In-Memory
• Security: Bcrypt, Argon2, JWT
• Testing: Jest, Supertest
• DevOps: Docker, GitHub Actions

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

👥 Authors

• Ahmed Salah - @a7medsa22

🙏 Acknowledgments

• Clean Architecture by Robert C. Martin
• Domain-Driven Design by Eric Evans
• NestJS Framework Team
• All contributors

📞 Support

• 📧 Email: ahmedsalahsotoy@gmail.com
• 🐛 Issues: GitHub Issues
• 📖 Docs: Full Documentation

---

⭐ If this project helped you, please give it a star!

📢 Share with your team and help others build better authentication systems!