# jcsb83/base-nestjs-backend architecture

> Architecture diagram of the GitHub repository jcsb83/base-nestjs-backend, 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
- Repository: https://github.com/jcsb83/base-nestjs-backend

## Overview

This repository is a NestJS HTTP API foundation rather than a domain-specific application: requests reach health and metrics endpoints, while bootstrap supplies validated configuration, global validation, Swagger, logging, and shutdown handling. The major runtime branches are health/readiness, Prometheus metrics, and shared request logging with selectable Log4js or Loki backends. The README documents these capabilities; unsampled implementation details are represented at their exact enclosing directories, and edges are limited to relationships shown in excerpts, the source index, or README.

Main entry points: [`src/main.ts`](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/main.ts) (API bootstrap), [`src/app.module.ts`](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/app.module.ts) (Root modules), [`src/modules/shared/shared.module.ts`](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/shared.module.ts) (Logger selection), [`src/modules/metrics/metrics.module.ts`](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/metrics/metrics.module.ts) (Metrics wiring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Application bootstrap"]
  node_api_boot["API bootstrap<br/>[main.ts]"]
  node_app_composition["Root modules<br/>[app.module.ts]"]
  node_api_docs["Swagger UI<br/>[main.ts]"]
  node_request_validation["Request validation<br/>[main.ts]"]
end

subgraph group_operations["Health and metrics"]
  node_health_endpoints["Health endpoints"]
  node_health_module["Health checks<br/>[health.module.ts]"]
  node_metrics_routes["Metrics endpoint"]
  node_metrics_capture["HTTP metrics capture"]
  node_metrics_registry["Prometheus registry<br/>[metrics.service.ts]"]
  node_metrics_module["Metrics wiring<br/>[metrics.module.ts]"]
end

subgraph group_logging["Request logging"]
  node_request_interceptor["Request log interceptor"]
  node_logger_provider["Logger selection<br/>[shared.module.ts]"]
  node_log4js_backend["Log4js backend"]
  node_loki_backend["Loki backend"]
  node_common_errors["HTTP error mapping"]
  node_response_dto["Response DTO<br/>[response.dto.ts]"]
  node_usecase_errors["Use-case errors<br/>[usecase.error.ts]"]
  node_error_levels["Error levels<br/>[errorLevel.enum.ts]"]
  node_repository_errors["Repository errors"]
  node_shared_utils["Shared utilities<br/>[utils.ts]"]
end

subgraph group_configuration["Configuration"]
  node_env_settings["Environment settings"]
  node_app_settings["Validated app config<br/>[app.config.ts]"]
end

node_http_client(("HTTP clients"))
node_loki_service["Loki service"]

node_http_client -->|"sends HTTP"| node_api_boot
node_api_boot -->|"creates app"| node_app_composition
node_api_boot -->|"reads config"| node_app_settings
node_api_boot -->|"configures docs"| node_api_docs
node_api_boot -->|"installs pipe"| node_request_validation
node_api_boot -->|"installs interceptor"| node_request_interceptor
node_app_composition -->|"loads module"| node_env_settings
node_app_composition -->|"loads module"| node_health_module
node_app_composition -->|"loads module"| node_metrics_module
node_app_composition -->|"loads module"| node_logger_provider
node_env_settings -->|"provides config"| node_app_settings
node_health_module -->|"registers routes"| node_health_endpoints
node_health_endpoints -->|"checks log mode"| node_app_settings
node_health_endpoints -->|"pings readiness"| node_loki_service
node_http_client -->|"checks health"| node_health_endpoints
node_metrics_module -->|"registers routes"| node_metrics_routes
node_metrics_module -->|"registers middleware"| node_metrics_capture
node_metrics_module -->|"provides service"| node_metrics_registry
node_metrics_routes -->|"reads metrics"| node_metrics_registry
node_metrics_capture -->|"records requests"| node_metrics_registry
node_http_client -->|"scrapes metrics"| node_metrics_routes
node_logger_provider -->|"selects by mode"| node_app_settings
node_logger_provider -->|"creates logger"| node_log4js_backend
node_logger_provider -->|"creates logger"| node_loki_backend
node_request_interceptor -->|"generates log ID"| node_shared_utils
node_request_interceptor -.->|"emits request logs"| node_logger_provider
node_loki_backend -->|"pushes logs"| node_loki_service
node_common_errors -->|"builds response"| node_response_dto
node_common_errors -->|"maps errors"| node_usecase_errors
node_usecase_errors -->|"reads level"| node_error_levels

click node_api_boot "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/main.ts"
click node_app_composition "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/app.module.ts"
click node_api_docs "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/main.ts"
click node_request_validation "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/main.ts"
click node_env_settings "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/app.config.module.ts"
click node_app_settings "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/app.config.ts"
click node_health_endpoints "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/health/health.controller.ts"
click node_health_module "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/health/health.module.ts"
click node_metrics_routes "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/metrics/metrics.controller.ts"
click node_metrics_capture "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/metrics/metrics.middleware.ts"
click node_metrics_registry "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/metrics/metrics.service.ts"
click node_metrics_module "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/metrics/metrics.module.ts"
click node_request_interceptor "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/interceptors/log-request.interceptor.ts"
click node_logger_provider "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/shared.module.ts"
click node_log4js_backend "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/services/log4jsLogger.service.ts"
click node_loki_backend "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/services/lokiLogger.service.ts"
click node_common_errors "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/controllers/common.controller.ts"
click node_response_dto "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/dto/response.dto.ts"
click node_usecase_errors "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/errors/usecase.error.ts"
click node_error_levels "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/errors/errorLevel.enum.ts"
click node_repository_errors "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/errors/repository.error.ts"
click node_shared_utils "https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/utils/utils.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_api_boot,node_app_composition,node_api_docs,node_request_validation,node_http_client toneBlue
class node_health_endpoints,node_health_module,node_metrics_routes,node_metrics_capture,node_metrics_registry,node_metrics_module toneAmber
class node_request_interceptor,node_logger_provider,node_log4js_backend,node_loki_backend,node_common_errors,node_response_dto,node_usecase_errors,node_error_levels,node_repository_errors,node_shared_utils toneMint
class node_env_settings,node_app_settings toneRose
class node_loki_service toneIndigo
```

## Components

### Application bootstrap

- [API bootstrap](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/main.ts): `src/main.ts`
- [Root modules](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/app.module.ts): `src/app.module.ts`
- [Swagger UI](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/main.ts): `src/main.ts`
- [Request validation](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/main.ts): `src/main.ts`

### Health and metrics

- [Health endpoints](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/health/health.controller.ts): `src/modules/health/health.controller.ts`
- [Health checks](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/health/health.module.ts): `src/modules/health/health.module.ts`
- [Metrics endpoint](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/metrics/metrics.controller.ts): `src/modules/metrics/metrics.controller.ts`
- [HTTP metrics capture](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/metrics/metrics.middleware.ts): `src/modules/metrics/metrics.middleware.ts`
- [Prometheus registry](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/metrics/metrics.service.ts): `src/modules/metrics/metrics.service.ts`
- [Metrics wiring](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/metrics/metrics.module.ts): `src/modules/metrics/metrics.module.ts`

### Request logging

- [Request log interceptor](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/interceptors/log-request.interceptor.ts): `src/modules/shared/interceptors/log-request.interceptor.ts`
- [Logger selection](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/shared.module.ts): `src/modules/shared/shared.module.ts`
- [Log4js backend](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/services/log4jsLogger.service.ts): `src/modules/shared/services/log4jsLogger.service.ts`
- [Loki backend](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/services/lokiLogger.service.ts): `src/modules/shared/services/lokiLogger.service.ts`
- [HTTP error mapping](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/controllers/common.controller.ts): `src/modules/shared/controllers/common.controller.ts`
- [Response DTO](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/dto/response.dto.ts): `src/modules/shared/dto/response.dto.ts`
- [Use-case errors](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/errors/usecase.error.ts): `src/modules/shared/errors/usecase.error.ts`
- [Error levels](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/errors/errorLevel.enum.ts): `src/modules/shared/errors/errorLevel.enum.ts`
- [Repository errors](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/errors/repository.error.ts): `src/modules/shared/errors/repository.error.ts`
- [Shared utilities](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/modules/shared/utils/utils.ts): `src/modules/shared/utils/utils.ts`

### Configuration

- [Environment settings](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/app.config.module.ts): `src/app.config.module.ts`
- [Validated app config](https://github.com/jcsb83/base-nestjs-backend/blob/main/src/app.config.ts): `src/app.config.ts`

### Other components

- **HTTP clients**
- **Loki service**

## Connections

- HTTP clients → API bootstrap: sends HTTP (evidence: `README.md`)
- API bootstrap → Root modules: creates app (evidence: `src/main.ts`)
- API bootstrap → Validated app config: reads config (evidence: `src/main.ts`)
- API bootstrap → Swagger UI: configures docs (evidence: `src/main.ts`)
- API bootstrap → Request validation: installs pipe (evidence: `src/main.ts`)
- API bootstrap → Request log interceptor: installs interceptor (evidence: `src/main.ts`)
- Root modules → Environment settings: loads module (evidence: `src/app.module.ts`)
- Root modules → Health checks: loads module (evidence: `src/app.module.ts`)
- Root modules → Metrics wiring: loads module (evidence: `src/app.module.ts`)
- Root modules → Logger selection: loads module (evidence: `src/app.module.ts`)
- Environment settings → Validated app config: provides config (evidence: `src/app.config.module.ts`)
- Health checks → Health endpoints: registers routes (evidence: `src/modules/health/health.module.ts`)
- Health endpoints → Validated app config: checks log mode (evidence: `src/modules/health/health.controller.ts`)
- Health endpoints → Loki service: pings readiness (evidence: `README.md`)
- HTTP clients → Health endpoints: checks health (evidence: `README.md`)
- Metrics wiring → Metrics endpoint: registers routes (evidence: `src/modules/metrics/metrics.module.ts`)
- Metrics wiring → HTTP metrics capture: registers middleware (evidence: `src/modules/metrics/metrics.module.ts`)
- Metrics wiring → Prometheus registry: provides service (evidence: `src/modules/metrics/metrics.module.ts`)
- Metrics endpoint → Prometheus registry: reads metrics (evidence: `src/modules/metrics/metrics.controller.ts`)
- HTTP metrics capture → Prometheus registry: records requests (evidence: `src/modules/metrics/metrics.middleware.ts`)
- HTTP clients → Metrics endpoint: scrapes metrics (evidence: `README.md`)
- Logger selection → Validated app config: selects by mode (evidence: `src/modules/shared/shared.module.ts`)
- Logger selection → Log4js backend: creates logger (evidence: `src/modules/shared/shared.module.ts`)
- Logger selection → Loki backend: creates logger (evidence: `src/modules/shared/shared.module.ts`)
- Request log interceptor → Shared utilities: generates log ID (evidence: `src/modules/shared/interceptors/log-request.interceptor.ts`)
- Request log interceptor → Logger selection: emits request logs (evidence: `src/modules/shared/shared.module.ts`)
- Loki backend → Loki service: pushes logs (evidence: `README.md`)
- HTTP error mapping → Response DTO: builds response (evidence: `src/modules/shared/controllers/common.controller.ts`)
- HTTP error mapping → Use-case errors: maps errors (evidence: `src/modules/shared/controllers/common.controller.ts`)
- Use-case errors → Error levels: reads level (evidence: `src/modules/shared/errors/usecase.error.ts`)
