# guindani-davi/nest-auth architecture

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

- Interactive diagram: https://gitdiagram.com/guindani-davi/nest-auth
- Repository: https://github.com/guindani-davi/nest-auth

## Overview

##### Project type and purpose
- This is a server-side application built with the NestJS framework (TypeScript, Node.js).
- It provides authentication functionality and database access, using Supabase (PostgreSQL) under the hood.
- It follows a modular, monolithic-service style rather than a microservices architecture.

##### File structure
- Top-level files
- package.json / package-lock.json: app dependencies and scripts
- nest-cli.json, tsconfig.json / tsconfig.build.json: TypeScript and Nest build configuration
- .husky, commitlint.config.js, .secretlintrc.json: Git hooks and linting
- src/
- main.ts: bootstrap point that creates and starts the Nest application
- app.module.ts / app.controller.ts / app.service.ts: the root module and a sample controller/service
- src/auth/
- auth.module.ts, auth.controller.ts, auth.service.ts: authentication module, exposing REST endpoints and business logic
- auth.guard.ts: route-protection guard
- dtos.ts: request/response definitions (Data Transfer Objects)
- repositories/: data-access repositories (generic interface + Supabase implementation)
- src/database/
- database.service.ts: generic DB connection/provider to be injected across modules
- types.ts: shared database types/interfaces
- supabase/
- config.toml: Supabase local dev configuration
- migrations/: SQL migrations for schema evolution (e.g., users table)

##### Extract README insights
- Starter app from NestJS, focusing on server-side, efficiency, scalability
- Standard scripts for start, dev, prod, tests, deployment pointers

##### Main components
a. Clients (e.g., Postman, Browser, Mobile App)
b. HTTP API Gateway (NestJS application entrypoint)
c. Nest Modules
- AppModule
- AuthModule
- DatabaseModule
d. Controllers (AppController, AuthController)
e. Services (AppService, AuthService, DatabaseService)
f. Repository Layer
- Repository interface
- SupabaseRepository implementation
g. External Database Service
- Supabase (PostgreSQL)
h. Development Tooling / CI
- Husky Git hooks
- commitlint
- CircleCI or other CI (implied by badges, though config not shown)
i. Deployment (optional: Mau / AWS)

##### Relationships and interactions
- Clients → HTTP → Nest’s main.ts / AppModule
- Controller layer handles incoming routes (e.g., /auth/login)
- Controllers invoke Service methods with DTOs
- Services call Repository interfaces for data persistence
- Repository implementation uses DatabaseService to connect to Supabase
- DatabaseService wraps a Supabase client library (Pg) and runs queries/migrations
- Database migrations evolve the schema before or during startup

##### Architectural patterns and design principles
- Modular architecture (NestJS Modules)
- Dependency Injection (inject Controllers, Services, Repositories)
- Clean separation: Controller → Service → Repository → External DB
- Interface abstraction for Repository (allows swapping DB backends)
- Use of Guards for route protection and authorization

- Be explicit about module boundaries (Auth vs App vs Database)
- DI graph direction (inject DatabaseService into repos, repos into services, services into controllers)
- External dependencies (Supabase engine, migrations, CI/CD)
- Do not over-fragment—capture every layer but keep it readable

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Clients["Clients (Postman, Browser, Mobile)"]:::external

    %% Nest Application
    subgraph "NestJS Application"
        direction TB
        %% Controllers Layer
        AppController["AppController"]:::controller
        AuthController["AuthController"]:::controller

        %% Services Layer
        AppService["AppService"]:::service
        AuthService["AuthService"]:::service

        %% Repository Layer
        RepoInterface["Repository Interface"]:::repo
        SupabaseRepo["SupabaseRepository"]:::repo

        %% Database Service
        DatabaseService["DatabaseService"]:::service

        %% Supporting Auth Components
        AuthGuard["AuthGuard"]:::external
        AuthDTOs["Auth DTOs"]:::external
    end

    %% External Database and Migrations
    subgraph "Database & Supabase"
        direction TB
        SupabaseDB["PostgreSQL (Supabase)"]:::db
        Migrations["DB Migrations"]:::external
        SupabaseConfig["Supabase Config"]:::external
    end

    %% Development & CI Tooling
    subgraph "Development & CI" 
        direction TB
        classDef tooling fill:#F5F5F5,stroke:#9E9E9E,stroke-dasharray:5 5
        Husky[".husky/ (Git Hooks)"]:::tooling
        CommitLint["commitlint.config.js"]:::tooling
    end

    %% Connections
    Clients -->|HTTP Requests| AppController
    Clients -->|HTTP Requests| AuthController

    AppController -->|calls| AppService
    AuthController -->|calls| AuthService
    AuthController -->|uses| AuthGuard
    AuthController -->|uses| AuthDTOs

    AppService -->|uses| RepoInterface
    AuthService -->|uses| RepoInterface
    AuthService -->|uses| AuthDTOs

    RepoInterface -->|implemented by| SupabaseRepo
    SupabaseRepo -->|injects| DatabaseService
    DatabaseService -->|connects to| SupabaseDB
    DatabaseService -->|runs| Migrations
    DatabaseService -->|loads config| SupabaseConfig

    %% Click Events
    click Clients "https://github.com/guindani-davi/nest-auth/tree/main/n/a"
    click AppController "https://github.com/guindani-davi/nest-auth/blob/main/src/app.controller.ts"
    click AppService "https://github.com/guindani-davi/nest-auth/blob/main/src/app.service.ts"
    click AuthController "https://github.com/guindani-davi/nest-auth/blob/main/src/auth/auth.controller.ts"
    click AuthService "https://github.com/guindani-davi/nest-auth/blob/main/src/auth/auth.service.ts"
    click AuthGuard "https://github.com/guindani-davi/nest-auth/blob/main/src/auth/auth.guard.ts"
    click AuthDTOs "https://github.com/guindani-davi/nest-auth/blob/main/src/auth/dtos.ts"
    click RepoInterface "https://github.com/guindani-davi/nest-auth/blob/main/src/auth/repositories/repository.ts"
    click SupabaseRepo "https://github.com/guindani-davi/nest-auth/blob/main/src/auth/repositories/supabase/repository.ts"
    click DatabaseService "https://github.com/guindani-davi/nest-auth/blob/main/src/database/database.service.ts"
    click SupabaseDB "https://github.com/guindani-davi/nest-auth/tree/main/n/a"
    click Migrations "https://github.com/guindani-davi/nest-auth/blob/main/supabase/migrations/20250909020531_add_users_table.sql"
    click SupabaseConfig "https://github.com/guindani-davi/nest-auth/blob/main/supabase/config.toml"
    click Husky "https://github.com/guindani-davi/nest-auth/tree/main/.husky/"
    click CommitLint "https://github.com/guindani-davi/nest-auth/blob/main/commitlint.config.js"

    %% Styles
    classDef controller fill:#D6E9FE,stroke:#4A90E2
    classDef service fill:#E8F4FD,stroke:#4A90E2
    classDef repo fill:#EDF7EF,stroke:#4A8F37
    classDef db fill:#E2FFE2,stroke:#0F0
    classDef external fill:#FFF3E0,stroke:#FB8C00
```
