# jcsb83/base-nestjs-backend-auth-db architecture

> Architecture diagram of the GitHub repository jcsb83/base-nestjs-backend-auth-db, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jcsb83/base-nestjs-backend-auth-db
- Repository: https://github.com/jcsb83/base-nestjs-backend-auth-db

## Overview

This is a NestJS HTTP authentication backend. Clients log in to receive access and refresh tokens; protected requests validate the access token against persisted user/session state, while refresh, logout, and session-management endpoints update that state. The graph also preserves the documented configuration, logging, health, and Prometheus capabilities. Edges use README statements and indexed imports or calls; some persistence links are dashed because the relevant use-case implementations were not excerpted.

Main entry points: [`src/modules/auth-db/presentation/controllers`](https://github.com/jcsb83/base-nestjs-backend-auth-db/tree/main/src/modules/auth-db/presentation/controllers) (Auth controllers), [`src/app.module.ts`](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/app.module.ts) (Root modules), [`src/main.ts`](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/main.ts) (Nest bootstrap), [`src/modules/auth-db/infrastructure/persistence/typeorm/repositories/session.repository.ts`](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/infrastructure/persistence/typeorm/repositories/session.repository.ts) (Session repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_entry["Nest bootstrap<br/>[main.ts]"]
  node_root["Root modules<br/>[app.module.ts]"]
  node_config["Validated config<br/>[app.config.ts]"]
  node_shared["Shared response/errors"]
end

subgraph group_auth["Authentication API"]
  node_auth_api["Auth controllers"]
  node_guard["JWT guard<br/>[jwt.authguard.ts]"]
end

subgraph group_application["Auth application"]
  node_login["Login use case<br/>[login.use-case.ts]"]
  node_refresh["Refresh use case"]
  node_sessions["Session use cases"]
  node_validate["Token validation"]
end

subgraph group_persistence["Auth persistence"]
  node_user_repo["User repository<br/>[user.repository.ts]"]
  node_session_repo["Session repository"]
  node_refresh_repo["Refresh-token repository"]
end

subgraph group_operations["Operations"]
  node_health["Health endpoints"]
  node_metrics["Metrics endpoints"]
  node_metrics_service["Metrics service<br/>[metrics.service.ts]"]
  node_logging["Request logging"]
  node_logger["Logger providers"]
end

node_client(("HTTP client"))
node_postgres[("PostgreSQL")]
node_loki["Loki"]

node_client -->|"sends requests"| node_entry
node_entry -->|"starts"| node_root
node_root -->|"loads configuration"| node_config
node_root -->|"loads auth module"| node_auth_api
node_root -->|"loads health module"| node_health
node_root -->|"loads metrics module"| node_metrics
node_client -->|"calls endpoints"| node_auth_api
node_auth_api -->|"executes login"| node_login
node_auth_api -->|"executes renewal"| node_refresh
node_auth_api -->|"executes session actions"| node_sessions
node_auth_api -->|"guards protected routes"| node_guard
node_guard -->|"validates token"| node_validate
node_login -.->|"checks credentials"| node_user_repo
node_validate -.->|"loads user"| node_user_repo
node_validate -.->|"checks session"| node_session_repo
node_refresh -.->|"replaces session"| node_session_repo
node_session_repo -->|"updates token records"| node_refresh_repo
node_user_repo -->|"queries"| node_postgres
node_session_repo -->|"reads and writes"| node_postgres
node_refresh_repo -->|"reads and writes"| node_postgres
node_auth_api -->|"formats errors"| node_shared
node_metrics -->|"reads metrics"| node_metrics_service
node_entry -->|"registers interceptor"| node_logging
node_entry -.->|"configures logging"| node_logger
node_logger -.->|"ships logs"| node_loki

click node_entry "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/main.ts"
click node_root "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/app.module.ts"
click node_config "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/app.config.ts"
click node_auth_api "https://github.com/jcsb83/base-nestjs-backend-auth-db/tree/main/src/modules/auth-db/presentation/controllers"
click node_login "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/application/use-cases/login.use-case.ts"
click node_refresh "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/application/use-cases/refreshToken.use-case.ts"
click node_sessions "https://github.com/jcsb83/base-nestjs-backend-auth-db/tree/main/src/modules/auth-db/application/use-cases"
click node_guard "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/infrastructure/guards/jwt.authguard.ts"
click node_validate "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/application/use-cases/validateToken.use-case.ts"
click node_user_repo "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/infrastructure/persistence/typeorm/repositories/user.repository.ts"
click node_session_repo "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/infrastructure/persistence/typeorm/repositories/session.repository.ts"
click node_refresh_repo "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/infrastructure/persistence/typeorm/repositories/refreshToken.repository.ts"
click node_shared "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/shared/controllers/common.controller.ts"
click node_health "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/health/health.controller.ts"
click node_metrics "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/metrics/metrics.controller.ts"
click node_metrics_service "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/metrics/metrics.service.ts"
click node_logging "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/shared/interceptors/log-request.interceptor.ts"
click node_logger "https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/shared/services/log4jsLogger.service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_root,node_config,node_shared,node_client toneBlue
class node_auth_api,node_guard,node_postgres toneAmber
class node_login,node_refresh,node_sessions,node_validate toneMint
class node_user_repo,node_session_repo,node_refresh_repo toneRose
class node_health,node_metrics,node_metrics_service,node_logging,node_logger,node_loki toneIndigo
```

## Components

### Application runtime

- [Nest bootstrap](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/main.ts): `src/main.ts`
- [Root modules](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/app.module.ts): `src/app.module.ts`
- [Validated config](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/app.config.ts): `src/app.config.ts`
- [Shared response/errors](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/shared/controllers/common.controller.ts): `src/modules/shared/controllers/common.controller.ts`

### Authentication API

- [Auth controllers](https://github.com/jcsb83/base-nestjs-backend-auth-db/tree/main/src/modules/auth-db/presentation/controllers): `src/modules/auth-db/presentation/controllers`
- [JWT guard](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/infrastructure/guards/jwt.authguard.ts): `src/modules/auth-db/infrastructure/guards/jwt.authguard.ts`

### Auth application

- [Login use case](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/application/use-cases/login.use-case.ts): `src/modules/auth-db/application/use-cases/login.use-case.ts`
- [Refresh use case](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/application/use-cases/refreshToken.use-case.ts): `src/modules/auth-db/application/use-cases/refreshToken.use-case.ts`
- [Session use cases](https://github.com/jcsb83/base-nestjs-backend-auth-db/tree/main/src/modules/auth-db/application/use-cases): `src/modules/auth-db/application/use-cases`
- [Token validation](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/application/use-cases/validateToken.use-case.ts): `src/modules/auth-db/application/use-cases/validateToken.use-case.ts`

### Auth persistence

- [User repository](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/infrastructure/persistence/typeorm/repositories/user.repository.ts): `src/modules/auth-db/infrastructure/persistence/typeorm/repositories/user.repository.ts`
- [Session repository](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/infrastructure/persistence/typeorm/repositories/session.repository.ts): `src/modules/auth-db/infrastructure/persistence/typeorm/repositories/session.repository.ts`
- [Refresh-token repository](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/auth-db/infrastructure/persistence/typeorm/repositories/refreshToken.repository.ts): `src/modules/auth-db/infrastructure/persistence/typeorm/repositories/refreshToken.repository.ts`

### Operations

- [Health endpoints](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/health/health.controller.ts): `src/modules/health/health.controller.ts`
- [Metrics endpoints](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/metrics/metrics.controller.ts): `src/modules/metrics/metrics.controller.ts`
- [Metrics service](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/metrics/metrics.service.ts): `src/modules/metrics/metrics.service.ts`
- [Request logging](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/shared/interceptors/log-request.interceptor.ts): `src/modules/shared/interceptors/log-request.interceptor.ts`
- [Logger providers](https://github.com/jcsb83/base-nestjs-backend-auth-db/blob/main/src/modules/shared/services/log4jsLogger.service.ts): `src/modules/shared/services/log4jsLogger.service.ts`

### Other components

- **HTTP client**
- **PostgreSQL**
- **Loki**

## Connections

- HTTP client → Nest bootstrap: sends requests
- Nest bootstrap → Root modules: starts (evidence: `src/main.ts`)
- Root modules → Validated config: loads configuration (evidence: `src/app.module.ts`)
- Root modules → Auth controllers: loads auth module (evidence: `src/app.module.ts`)
- Root modules → Health endpoints: loads health module (evidence: `src/app.module.ts`)
- Root modules → Metrics endpoints: loads metrics module (evidence: `src/app.module.ts`)
- HTTP client → Auth controllers: calls endpoints
- Auth controllers → Login use case: executes login (evidence: `src/modules/auth-db/presentation/controllers/login.controller.ts`)
- Auth controllers → Refresh use case: executes renewal (evidence: `src/modules/auth-db/presentation/controllers/refresh.controller.ts`)
- Auth controllers → Session use cases: executes session actions (evidence: `src/modules/auth-db/presentation/controllers/session.controller.ts`)
- Auth controllers → JWT guard: guards protected routes (evidence: `src/modules/auth-db/presentation/controllers/session.controller.ts`)
- JWT guard → Token validation: validates token (evidence: `src/modules/auth-db/infrastructure/guards/jwt.authguard.ts`)
- Login use case → User repository: checks credentials
- Token validation → User repository: loads user
- Token validation → Session repository: checks session
- Refresh use case → Session repository: replaces session
- Session repository → Refresh-token repository: updates token records (evidence: `src/modules/auth-db/infrastructure/persistence/typeorm/repositories/session.repository.ts`)
- User repository → PostgreSQL: queries (evidence: `src/modules/auth-db/infrastructure/persistence/typeorm/repositories/user.repository.ts`)
- Session repository → PostgreSQL: reads and writes (evidence: `src/modules/auth-db/infrastructure/persistence/typeorm/repositories/session.repository.ts`)
- Refresh-token repository → PostgreSQL: reads and writes (evidence: `src/modules/auth-db/infrastructure/persistence/typeorm/repositories/refreshToken.repository.ts`)
- Auth controllers → Shared response/errors: formats errors (evidence: `src/modules/auth-db/presentation/controllers/refresh.controller.ts`)
- Metrics endpoints → Metrics service: reads metrics (evidence: `src/modules/metrics/metrics.controller.ts`)
- Nest bootstrap → Request logging: registers interceptor (evidence: `src/main.ts`)
- Nest bootstrap → Logger providers: configures logging
- Logger providers → Loki: ships logs
