# felipeoj/api_auth architecture

> Architecture diagram of the GitHub repository felipeoj/api_auth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/felipeoj/api_auth
- Repository: https://github.com/felipeoj/api_auth

## Overview

##### Project Type and Purpose
- This is a backend API built with NestJS and TypeScript, focused on secure authentication (JWT & 2FA), user management, and email notifications. It follows Clean Architecture principles, separating concerns into modules, controllers, services, use-cases, domain entities, and infrastructure.

##### Key Layers & Components
a. Presentation/API Layer
- Controllers (src/auth/auth.controller.ts, src/users/users.controller.ts, src/auth/controllers/two-factor.controller.ts)
- Validation Pipes (ZodValidationPipe in src/common/pipes)
- Guards & Strategies (JWT guards and passport strategies in src/auth/infra)
b. Application Layer
- DTOs (src/application/dto/*.dto.ts)
- Use-Cases (login, register, refresh, handle-refresh, 2FA enable/verify in src/auth/use-cases)
c. Domain Layer
- Entities (User, Auth in src/core/domain/entities)
- Domain Services (e.g., user-validation.service.ts)
- Repository Interfaces (user-repository.interface.ts)
d. Infrastructure Layer
- Database (Prisma client in src/database/prisma.service.ts, prisma-user.repository.ts)
- Email (email.client.ts, email.service.ts in src/infra/email)
- Providers (dependency injection tokens in src/infra/providers)
e. Cross-Cutting
- AppModule wiring all modules
- Configuration (.env, @nestjs/config)
- Logging, Testing (Jest)

##### External Dependencies & Services
- PostgreSQL (via Prisma ORM)
- Email Provider (SMTP or external API via email.client.ts)
- Passport.js strategies (JWT access & refresh)
- qrcode for 2FA QR generation

##### Interactions & Data Flows
1. Client → HTTP Request → NestJS Controller
2. Controller → Validate DTO via Zod Pipe → Invoke Use-Case
3. Use-Case → Domain Service + Repository Interface → Prisma Repository → Database
4. On 2FA enable: Use-Case generates secret, QR code → returns to Controller → Client
5. Authentication: JWT Strategy Guard intercepts protected routes → validates token → attaches user to request
6. Refresh flow: Controller reads HTTP-only cookie → Use-Case refreshes tokens → sets new cookie + returns access token
7. Email notifications (e.g., verification) via EmailService → EmailClient → external SMTP/API

##### Architectural Patterns & Principles
- Clean Architecture (clear separation: Controllers, DTOs, Use-Cases, Domain, Infrastructure)
- Dependency Inversion (use repository interfaces injected into services)
- Single Responsibility (each module focuses on one concern: auth, users, email)
- Modularization (NestJS modules encapsulate related providers, controllers, exports)

- Critical flows (e.g., token issuance, 2FA verification)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation/API Layer
    subgraph "Presentation/API Layer"
        direction TB
        AuthController["AuthController"]:::frontend
        UsersController["UsersController"]:::frontend
        TwoFactorController["TwoFactorController"]:::frontend
        ZodValidationPipe["ZodValidationPipe"]:::frontend
        JWTAuthGuard["JWT Auth Guard"]:::frontend
        JWTStrategy["JWT Strategy"]:::frontend
        JWTRefreshStrategy["JWT Refresh Strategy"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        LoginDTO["Login DTO"]:::application
        RegisterDTO["Register DTO"]:::application
        Verify2FADTO["Verify 2FA DTO"]:::application
        RegisterUserUC["Register User Use-Case"]:::application
        RefreshAccessTokenUC["Refresh Access Token Use-Case"]:::application
        HandleRefreshTokenUC["Handle Refresh Token Use-Case"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        UserEntity["User Entity"]:::domain
        AuthEntity["Auth Entity"]:::domain
        UserRoleEnum["User Role Enum"]:::domain
        UserSchema["User Schema"]:::domain
        UserValidationService["User Validation Domain Service"]:::domain
        UserRepoInterface["User Repository Interface"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        PrismaClientService["Prisma Client Service"]:::infra
        PrismaUserRepo["Prisma User Repository"]:::infra
        UserInfraModule["User Infrastructure Module"]:::infra
        EmailClient["Email Client"]:::infra
        EmailService["Email Service"]:::infra
        EmailModule["Email Module"]:::infra
        EmailProviderToken["Email Provider Token"]:::infra
        AppModule["AppModule"]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        PostgreSQL["PostgreSQL"]:::external
        SMTP["SMTP/Email API"]:::external
    end

    %% Relationships
    AuthController -->|uses| ZodValidationPipe
    AuthController -->|protected by| JWTAuthGuard
    JWTAuthGuard -->|uses| JWTStrategy
    JWTAuthGuard -->|uses| JWTRefreshStrategy
    AuthController -->|calls| RegisterUserUC
    AuthController -->|calls| RefreshAccessTokenUC
    AuthController -->|calls| HandleRefreshTokenUC

    TwoFactorController -->|calls| Auth2FAService["Auth 2FA Service"]:::application

    RegisterUserUC -->|validates via| UserValidationService
    RegisterUserUC -->|depends on| UserRepoInterface
    RefreshAccessTokenUC -->|depends on| UserRepoInterface
    HandleRefreshTokenUC -->|depends on| UserRepoInterface

    UserRepoInterface -->|implemented by| PrismaUserRepo
    PrismaUserRepo -->|uses| PrismaClientService
    PrismaClientService -->|connects to| PostgreSQL

    EmailService -->|uses| EmailClient
    EmailClient -->|sends to| SMTP
    RegisterUserUC -->|sends email via| EmailService

    AppModule --> AuthController
    AppModule --> UsersController
    AppModule --> TwoFactorController
    AppModule --> RegisterUserUC
    AppModule --> RefreshAccessTokenUC
    AppModule --> HandleRefreshTokenUC
    AppModule --> UserInfraModule
    AppModule --> EmailModule

    %% Click Events
    click AuthController "https://github.com/felipeoj/api_auth/blob/main/src/auth/auth.controller.ts"
    click UsersController "https://github.com/felipeoj/api_auth/blob/main/src/users/users.controller.ts"
    click TwoFactorController "https://github.com/felipeoj/api_auth/blob/main/src/auth/controllers/two-factor.controller.ts"
    click ZodValidationPipe "https://github.com/felipeoj/api_auth/blob/main/src/common/pipes/zod-validation.pipe.ts"
    click JWTAuthGuard "https://github.com/felipeoj/api_auth/blob/main/src/auth/infra/guards/jwt-auth.guard.ts"
    click JWTStrategy "https://github.com/felipeoj/api_auth/blob/main/src/auth/infra/strategies/jwt.strategy.ts"
    click JWTRefreshStrategy "https://github.com/felipeoj/api_auth/blob/main/src/auth/infra/strategies/jwt-refresh.strategy.ts"
    click LoginDTO "https://github.com/felipeoj/api_auth/blob/main/src/application/dto/login.dto.ts"
    click RegisterDTO "https://github.com/felipeoj/api_auth/blob/main/src/application/dto/register.dto.ts"
    click Verify2FADTO "https://github.com/felipeoj/api_auth/blob/main/src/application/dto/verify-2fa.dto.ts"
    click RegisterUserUC "https://github.com/felipeoj/api_auth/blob/main/src/auth/use-cases/register-user.use-case.ts"
    click RefreshAccessTokenUC "https://github.com/felipeoj/api_auth/blob/main/src/auth/use-cases/refresh-access-token.use-case.ts"
    click HandleRefreshTokenUC "https://github.com/felipeoj/api_auth/blob/main/src/auth/use-cases/handle-refresh-token.use-case.ts"
    click Auth2FAService "https://github.com/felipeoj/api_auth/blob/main/src/auth/services/auth-2fa.service.ts"
    click UserEntity "https://github.com/felipeoj/api_auth/blob/main/src/core/domain/entities/user.entity.ts"
    click AuthEntity "https://github.com/felipeoj/api_auth/blob/main/src/core/domain/entities/auth.entity.ts"
    click UserRoleEnum "https://github.com/felipeoj/api_auth/blob/main/src/core/domain/entities/user-role.enum.ts"
    click UserSchema "https://github.com/felipeoj/api_auth/blob/main/src/core/domain/entities/user.schema.ts"
    click UserValidationService "https://github.com/felipeoj/api_auth/blob/main/src/core/domain/services/user-validation.service.ts"
    click UserRepoInterface "https://github.com/felipeoj/api_auth/blob/main/src/core/domain/repositories/user-repository.interface.ts"
    click PrismaClientService "https://github.com/felipeoj/api_auth/blob/main/src/database/prisma.service.ts"
    click PrismaUserRepo "https://github.com/felipeoj/api_auth/blob/main/src/database/prisma/prisma-user.repository.ts"
    click UserInfraModule "https://github.com/felipeoj/api_auth/blob/main/src/database/prisma/user-infra.module.ts"
    click EmailClient "https://github.com/felipeoj/api_auth/blob/main/src/infra/email/email.client.ts"
    click EmailService "https://github.com/felipeoj/api_auth/blob/main/src/infra/email/email.service.ts"
    click EmailModule "https://github.com/felipeoj/api_auth/blob/main/src/infra/email/email.module.ts"
    click EmailProviderToken "https://github.com/felipeoj/api_auth/blob/main/src/infra/providers/email.provider.ts"
    click AppModule "https://github.com/felipeoj/api_auth/blob/main/src/app.module.ts"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef application fill:#A9DFBF,stroke:#196F3D,color:#145A32
    classDef domain fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef infra fill:#F5CBA7,stroke:#A04000,color:#78281F
    classDef external fill:#D5D8DC,stroke:#566573,color:#212F3D
```
