nestforge-generator 0.1.0

package/templates/typeorm/ARCHITECTURE.pt-BR.md

@@ -0,0 +1,156 @@
+# Arquitetura
+
+[English](ARCHITECTURE.md) | **Português**
+
+Este documento explica como o NestForge com TypeORM está organizado e por que certas decisões de design foram tomadas.
+
+## Visão geral
+
+```text
+Request → main.ts (pipes, filters e interceptors globais)
+  → Guards de autenticação e autorização
+  → Controller (valida DTO e delega)
+  → Service (regra de negócio)
+  → Repository do TypeORM
+  → PostgreSQL, MySQL ou SQLite
+  → ClassSerializerInterceptor
+  → Response
+```
+
+Cada módulo de domínio segue a mesma estrutura:
+
+```text
+<modulo>/
+├── dto/                    # schemas Zod e DTOs
+├── entities/               # entidades persistidas pelo TypeORM
+├── <modulo>.controller.ts  # recebe a request e chama o service
+├── <modulo>.service.ts     # regras de negócio
+├── <modulo>.service.spec.ts
+└── <modulo>.module.ts      # dependências, repositories e exports
+```
+
+Controllers não acessam repositories diretamente. Toda operação passa pelo service, mantendo as regras de negócio centralizadas e testáveis.
+
+Os módulos registram suas entidades com:
+
+TypeOrmModule.forFeature([
+    UserEntity,
+])
+
+Os services recebem os repositories com:
+
+@InjectRepository(UserEntity) private readonly usersRepository: Repository<UserEntity>
+
+A conexão global fica em src/database/database.module.ts. As opções específicas de PostgreSQL, MySQL e SQLite ficam em src/database/typeorm-options.ts.
+
+## Decisões de design
+
+### Por que Zod em vez de class-validator?
+
+Com Zod, o schema é a fonte principal para validação e documentação. O nestjs-zod transforma schemas em DTOs, enquanto patchNestJsSwagger() permite que o Swagger interprete esses schemas.
+
+Isso reduz a duplicação entre decorators de validação e documentação.
+
+### Por que usar os repositories do TypeORM diretamente?
+
+Repository<Entity> já oferece uma abstração testável e tipada para persistência. Criar outra camada genérica de repository por cima adicionaria indireção sem trazer benefício para este boilerplate.
+
+Os testes unitários substituem os repositories por objetos com vi.fn(), sem precisar iniciar banco ou aplicação Nest completa.
+
+Uma camada adicional pode ser criada posteriormente se o projeto precisar de regras complexas de persistência ou múltiplas fontes de dados.
+
+### Por que synchronize fica desabilitado?
+
+O template usa:
+
+synchronize: false
+
+Mudanças no banco devem passar por migrations versionadas. Isso evita alterações automáticas e potencialmente destrutivas no schema, principalmente em produção.
+
+As migrations são geradas e executadas com:
+
+npm run migration:generate -- src/database/migrations/NomeDaMigration
+npm run migration:run
+
+### Por que permissions são um mapa em código?
+
+O mapa ROLE_PERMISSIONS atende projetos com poucas roles fixas e deixa as permissões fáceis de auditar.
+
+Se o projeto precisar de roles criadas dinamicamente, o mapa pode ser substituído por entidades como Role, Permission e RolePermission.
+
+### Por que BullMQ para envio de e-mails?
+
+SMTP é uma operação externa que pode falhar ou demorar. Colocar o envio em uma fila permite que a requisição respondadepois de enfileirar o trabalho, enquanto o MailProcessor realiza o envio e as tentativas posteriores.
+
+### Por que armazenar o hash dos refresh tokens?
+
+Um JWT não pode ser revogado antes de expirar. O armazenamento do hash permite:
+
+  - logout;
+  - rotação do refresh token;
+  - invalidação após troca de senha;
+  - bloqueio da reutilização de tokens revogados.
+
+O token original não é persistido.
+
+### Por que UserEntity usa @Exclude()?
+
+O repository precisa acessar passwordHash em operações como login, mas esse campo nunca deve aparecer na resposta HTTP.
+
+O @Exclude() combinado com ClassSerializerInterceptor cria uma barreira de serialização para impedir o vazamento do hash.
+
+### Por que Session/Cookies usa armazenamento persistente?
+
+A estratégia Session/Cookies usa express-session com connect-typeorm. As sessões ficam na tabela sessions, em vez da memória do processo.
+
+Isso permite reiniciar ou escalar a aplicação sem perder todas as sessões ativas.
+
+### Como funciona a proteção CSRF?
+
+Na estratégia Session/Cookies, a aplicação usa um token CSRF associado à sessão. Requisições que alteram estado precisam enviar esse token pelo header:
+
+x-csrf-token
+
+O middleware compara o token recebido com o token armazenado na sessão.
+
+Na estratégia JWT com Bearer token, o navegador não envia automaticamente a credencial no cookie, então esse fluxo de CSRF não é necessário.
+
+## Estratégias de autenticação
+
+### JWT
+
+1. Cadastro ou login valida o usuário.
+2. TokenService emite access e refresh tokens.
+3. O hash do refresh token é armazenado no banco.
+4. JwtAuthGuard valida o Bearer token.
+5. O refresh revoga o token anterior e emite um novo par.
+6. O logout revoga o refresh token.
+
+### Session/Cookies
+
+1. Cadastro ou login valida o usuário.
+2. A sessão é regenerada para evitar session fixation.
+3. O usuário e o token CSRF são armazenados na sessão.
+4. O navegador recebe o cookie nestforge.sid.
+5. SessionAuthGuard protege as rotas.
+6. O logout destrói a sessão.
+
+### OAuth
+
+Google e GitHub são vinculados por OAuthAccountEntity. Se o e-mail ainda não estiver cadastrado, um usuário é criado e associado ao provedor.
+
+## Banco e entidades
+
+As principais entidades são:
+
+- UserEntity;
+- OAuthAccountEntity;
+- RefreshTokenEntity, quando tokens estiverem habilitados;
+- SessionEntity, quando Session/Cookies estiver habilitada;
+- entidades de recuperação e verificação de e-mail, quando aplicáveis.
+
+Entidades condicionais usam os marcadores do gerador para que apenas os arquivos e relacionamentos necessários permaneçam no projeto final.
+
+## Onde adicionar um módulo
+
+Para adicionar um novo domínio, consulte docs/adding-a-module.md (docs/adding-a-module.md).

package/templates/typeorm/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+**English** | [Português](CODE_OF_CONDUCT.pt-BR.md)
+
+## Our commitment
+
+We, as members, contributors, and maintainers, pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Respecting different viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery
+- Offensive comments or personal/political attacks
+- Public or private harassment
+- Publishing other people's private information without permission
+
+## Enforcement
+
+Instances of abusive behavior may be reported by opening an issue marked as confidential or by contacting the project maintainer directly. All complaints will be reviewed and investigated.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/templates/typeorm/CODE_OF_CONDUCT.pt-BR.md

@@ -0,0 +1,27 @@
+# Código de Conduta
+
+[English](CODE_OF_CONDUCT.md) | **Português**
+
+## Nosso compromisso
+
+Nós, como membros, contribuintes e mantenedores, nos comprometemos a fazer da participação neste projeto uma experiência livre de assédio para todos, independentemente de idade, corpo, deficiência, etnia, identidade e expressão de gênero, nível de experiência, nacionalidade, aparência pessoal, raça, religião ou orientação sexual.
+
+## Nossos padrões
+
+Exemplos de comportamento que contribuem para um ambiente positivo:
+- Usar linguagem acolhedora e inclusiva
+- Respeitar pontos de vista e experiências diferentes
+- Aceitar críticas construtivas com elegância
+- Focar no que é melhor para a comunidade
+
+Exemplos de comportamento inaceitável:
+- Uso de linguagem ou imagens sexualizadas
+- Comentários ofensivos ou ataques pessoais/políticos
+- Assédio público ou privado
+- Publicar informações privadas de terceiros sem permissão
+
+## Aplicação
+
+Casos de comportamento abusivo podem ser reportados abrindo uma issue marcada como confidencial ou entrando em contato diretamente com o mantenedor do projeto. Todas as reclamações serão revisadas e investigadas.
+
+Este Código de Conduta é adaptado do [Contributor Covenant](https://www.contributor-covenant.org), versão 2.1.

package/templates/typeorm/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to NestForge
+
+**English** | [Português](CONTRIBUTING.pt-BR.md)
+
+Thank you for considering contributing! 🎉
+
+## Getting started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/nestforge.git`
+3. Create a branch: `git checkout -b feat/feature-name`
+4. Start the environment: `docker compose up` (or `npm install` + `npm run start:dev`)
+5. Make your changes
+6. Run tests and lint before committing: `npm run test && npm run lint`
+7. Commit according to the convention below
+8. Open a Pull Request describing what was changed and why
+
+## Commit convention
+
+We use Portuguese commit messages following [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: adiciona autenticação via Google OAuth
+fix: corrige validação do refresh token
+docs: atualiza guia de instalação
+test: adiciona testes de integração para users
+refactor: extrai lógica de hash para utils
+chore: atualiza dependências
+```
+
+## Code standards
+
+- If your code is related to an optional CLI feature (Swagger, Redis, RBAC, etc.), mark it according to [`docs/feature-markers.md`](docs/feature-markers.md). Without this, the CLI cannot remove the code when someone disables the feature.
+- Strict TypeScript (no unjustified `any`)
+- Always validate input through Zod (DTOs)
+- No business logic in controllers — controllers only orchestrate, services handle the logic
+- Every new route requires Swagger decorators (`@ApiTags`, `@ApiOperation`, etc.)
+- Every new feature requires tests (at least unit tests)
+
+## Reporting bugs
+
+Open an issue containing:
+
+- A description of the problem
+- Steps to reproduce it
+- Expected versus actual behavior
+- Node version / environment (Docker or local)
+
+## Suggesting features
+
+Before implementing, open an issue with the `enhancement` label describing the problem the feature solves. This avoids rework if the approach needs to be discussed.
+
+## Code of Conduct
+
+By contributing, you agree to follow the project's [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---

package/templates/typeorm/CONTRIBUTING.pt-BR.md

@@ -0,0 +1,54 @@
+# Contribuindo com o NestForge
+
+[English](CONTRIBUTING.md) | **Português**
+
+Obrigado por considerar contribuir! 🎉
+
+## Como começar
+
+1. Faça um fork do repositório
+2. Clone o seu fork: `git clone https://github.com/SEU_USUARIO/nestforge.git`
+3. Crie uma branch: `git checkout -b feat/nome-da-feature`
+4. Suba o ambiente: `docker compose up` (ou `npm install` + `npm run start:dev`)
+5. Faça suas alterações
+6. Rode os testes e o lint antes de commitar: `npm run test && npm run lint`
+7. Commit seguindo o padrão abaixo
+8. Abra um Pull Request descrevendo o que foi feito e por quê
+
+## Padrão de commits
+
+Usamos commits em português, seguindo [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: adiciona autenticação via Google OAuth
+fix: corrige validação do refresh token
+docs: atualiza guia de instalação
+test: adiciona testes de integração para users
+refactor: extrai lógica de hash para utils
+chore: atualiza dependências
+```
+
+## Padrões de código
+
+- Se o seu código for ligado a um recurso opcional da CLI (Swagger, Redis, RBAC, etc.), marque ele seguindo [`docs/feature-markers.md`](docs/feature-markers.md) — sem isso, a CLI não consegue remover o trecho quando alguém desliga o recurso.
+- TypeScript estrito (sem `any` sem justificativa)
+- Validação de entrada sempre via Zod (DTOs)
+- Nada de lógica de negócio no controller — controller só orquestra, service resolve
+- Toda rota nova precisa de decorators de Swagger (`@ApiTags`, `@ApiOperation`, etc)
+- Toda feature nova precisa de teste (unitário no mínimo)
+
+## Reportando bugs
+
+Abra uma issue com:
+- Descrição do problema
+- Passos para reproduzir
+- Comportamento esperado vs. atual
+- Versão do Node / ambiente (Docker ou local)
+
+## Sugerindo features
+
+Abra uma issue com a tag `enhancement` descrevendo o problema que a feature resolve antes de sair implementando — isso evita retrabalho caso a abordagem precise ser discutida.
+
+## Código de conduta
+
+Ao contribuir, você concorda em seguir o [Código de Conduta](CODE_OF_CONDUCT.pt-BR.md) do projeto.

package/templates/typeorm/Dockerfile

@@ -0,0 +1,43 @@
+# --- Base ---
+FROM node:20-alpine AS base
+
+WORKDIR /app
+
+COPY package*.json ./
+
+# --- Dependencies ---
+FROM base AS deps
+
+RUN npm ci
+
+# --- Development ---
+FROM deps AS development
+
+COPY . .
+
+EXPOSE 3000
+
+CMD ["npm", "run", "start:dev"]
+
+# --- Build ---
+FROM deps AS build
+
+COPY . .
+
+RUN npm run build
+RUN npm prune --omit=dev
+
+# --- Production ---
+FROM node:20-alpine AS production
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/package.json ./package.json
+
+EXPOSE 3000
+
+CMD ["node", "dist/main.js"]

package/templates/typeorm/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeiel Jedson Leão Alves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/typeorm/README.md

@@ -0,0 +1,266 @@
+# NestForge
+
+**English** | [Português](README.pt-BR.md)
+
+> Production-ready NestJS starter with TypeORM, Authentication, Docker, Testing, CI/CD and Clean Architecture.
+
+[![CI](https://github.com/jeiel2013/nestforge/actions/workflows/ci.yml/badge.svg)](https://github.com/jeiel2013/nestforge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![NestJS](https://img.shields.io/badge/NestJS-11-red)](https://nestjs.com)
+
+NestForge is a NestJS starter designed to accelerate the beginning of serious backend projects, with complete authentication, clean architecture, security, and observability already configured. The idea is to clone it, run `docker compose up`, and have an API ready to evolve.
+
+## ✨ Features
+
+- 🔐 **Configurable authentication** — JWT with access/refresh tokens, TypeORM-backed Session/Cookies, OAuth-only, or no authentication
+- 🌐 **OAuth** — Google and GitHub, integrated with the selected token or session strategy
+- 👥 **RBAC** — Roles (Admin, Manager, User) and granular Permissions
+- 🛡️ **Security** — Helmet, CORS, Rate Limiting, validation, and serialization with Zod
+- 🗄️ **Database** — TypeORM with PostgreSQL, MySQL, or SQLite
+- 📨 **Email** — queues with BullMQ + Redis, locally tested with Mailpit
+- 📄 **Automatic documentation** — Swagger
+- 🪵 **Structured logs** — Pino
+- ✅ **Tests** — unit and integration tests with Vitest
+- 🐳 **Docker** — complete environment with a single command
+- ⚙️ **CI/CD** — GitHub Actions (build, lint, test)
+
+## 🧱 Stack
+
+| Layer | Technology |
+|---|---|
+| Framework | NestJS + TypeScript |
+| ORM | TypeORM |
+| Database | PostgreSQL, MySQL, or SQLite |
+| Cache / Queues | Redis + BullMQ |
+| Authentication | JWT, Session/Cookies, or OAuth with Passport |
+| Validation | Zod + nestjs-zod (schemas automatically become DTOs + Swagger) |
+| Docs | Swagger |
+| Email (dev) | Mailpit |
+| Tests | Vitest |
+| CI | GitHub Actions |
+
+## 📁 Folder structure
+
+```
+src/
+│
+├── auth/          # login, sessions/tokens, OAuth, guards, and strategies
+├── users/         # user CRUD
+├── common/        # decorators, filters, guards, interceptors, pipes, utilities
+├── config/        # typed and validated configuration (env)
+├── database/      # DataSource, configuration, migrations, and seed
+├── modules/       # additional domain modules
+├── shared/        # code shared between modules
+├── jobs/          # queues and workers (BullMQ)
+├── mail/          # email templates and delivery
+└── main.ts
+```
+
+## 🚀 Getting started
+
+### Prerequisites
+
+- Node.js 20+
+- Docker and Docker Compose
+
+### Running with Docker (recommended)
+
+```bash
+git clone https://github.com/jeiel2013/nestforge.git
+cd nestforge
+cp .env.example .env
+docker compose up
+```
+
+This starts the API, PostgreSQL, Redis, and Mailpit (email interface at `http://localhost:8025`).
+
+### Running locally
+
+```bash
+npm install
+cp .env.example .env
+npm run migration:generate -- src/database/migrations/InitialSchema
+npm run migration:run
+npm run seed
+npm run start:dev
+```
+
+Swagger documentation is available at `http://localhost:3000/docs`.
+
+## 🔑 Roles & Permissions
+
+| Role | Description |
+|---|---|
+| `ADMIN` | full system access |
+| `MANAGER` | manages users and reports |
+| `USER` | standard access |
+
+Permissions are granular (`user:create`, `user:delete`, `report:read`, etc.) and combined with roles through decorators (`@Roles()`, `@Permissions()`).
+
+## 🗺️ Roadmap
+
+- [x] JWT authentication
+- [x] Session/Cookies authentication
+- [x] Google/GitHub OAuth
+- [x] OAuth-only strategy
+- [x] Generation without authentication
+- [x] Refresh Token
+- [x] Docker
+- [x] CI (build, lint, test)
+- [x] OAuth (Google/GitHub)
+- [x] File uploads
+- [x] Queues (BullMQ)
+- [x] Transactional email
+- [x] Complete RBAC (granular permissions)
+- [x] Complete integration tests
+- [x] Complete documentation (Swagger + architecture guide)
+
+See the detailed [ROADMAP.md](ROADMAP.md).
+
+### Configuring social login (OAuth)
+
+To enable login through Google and GitHub, create an OAuth App with each provider and fill in `.env`:
+
+```bash
+APP_URL=http://localhost:3000
+
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+```
+
+- **Google**: create credentials in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) and configure the callback URL as `{APP_URL}/auth/google/callback`.
+- **GitHub**: create an OAuth App under `Settings > Developer settings > OAuth Apps` and configure the callback URL as `{APP_URL}/auth/github/callback`.
+
+Then access `GET /auth/google` or `GET /auth/github`. On callback, the API issues access/refresh tokens or establishes a cookie-based session according to the selected strategy. On first access, an account is created and linked to the provider.
+
+### Session/Cookies authentication
+
+When the project is generated with Session/Cookies, registration and login create a session persisted in the database through `connect-typeorm`. The identifier is sent in the `nestforge.sid` cookie, configured with `httpOnly`, `sameSite=lax`, and `secure` in production.
+
+Configure `.env`:
+
+```bash
+SESSION_SECRET=use-a-secret-with-at-least-32-characters
+SESSION_MAX_AGE=604800000
+```
+
+### Password recovery and email verification
+
+Every registration (`POST /auth/register`) automatically sends a verification email. Emails are queued with BullMQ/Redis and processed by a worker that sends them over SMTP. In development, everything goes to Mailpit (`http://localhost:8025`), so nothing is actually sent over the internet.
+
+| Route | What it does |
+|---|---|
+| `POST /auth/forgot-password` | Receives an `email` and queues the password reset link (the response is always generic and does not reveal whether the email exists) |
+| `POST /auth/reset-password` | Receives a `token` + `password` and changes the password; it also revokes the user's active refresh tokens |
+| `GET /auth/verify-email?token=...` | Confirms the email from the received link |
+
+Reset and verification tokens expire after 1 hour and 24 hours, respectively, and can only be used once.
+
+## 🔑 Roles & Permissions
+
+| Role | Description |
+|---|---|
+| `ADMIN` | full system access |
+| `MANAGER` | manages users and reports |
+| `USER` | standard access |
+
+Each role has a fixed set of permissions mapped in `src/common/constants/role-permissions.ts`:
+
+| Permission | ADMIN | MANAGER | USER |
+|---|:---:|:---:|:---:|
+| `user:create` | ✅ | ❌ | ❌ |
+| `user:read` | ✅ | ✅ | ✅ |
+| `user:update` | ✅ | ✅ | ❌ |
+| `user:delete` | ✅ | ❌ | ❌ |
+| `report:read` | ✅ | ✅ | ❌ |
+
+On routes, use `@Permissions(Permission.UserCreate)` to require a specific permission or `@Roles(Role.ADMIN)` when role-based control is enough. Both guards (`RolesGuard` and `PermissionsGuard`) run globally and only block a route when it has the corresponding decorator.
+
+## 👥 Users: pagination, filters, and avatar
+
+`GET /users` accepts query parameters for paginating and filtering the list:
+
+```bash
+GET /users?page=2&limit=20&search=jeiel&role=ADMIN
+```
+
+| Parameter | Description |
+|---|---|
+| `page` | current page (default: 1) |
+| `limit` | items per page, up to 100 (default: 10) |
+| `search` | searches by name or email (case-insensitive) |
+| `role` | filters by `ADMIN`, `MANAGER`, or `USER` |
+
+The response uses the format `{ data, meta: { total, page, limit, totalPages } }`.
+
+To change the authenticated user's avatar:
+
+```bash
+curl -X POST http://localhost:3000/users/me/avatar \
+  -H "Authorization: Bearer <accessToken>" \
+  -F "file=@/path/to/photo.png"
+```
+
+PNG, JPEG, and WEBP files up to 2 MB are accepted. The file is saved under `./uploads/avatars` and served at `/uploads/avatars/<file>`.
+
+## 🛡️ Security: serialization and CSRF
+
+All input validation (`body`, `query`) uses **Zod** through [`nestjs-zod`](https://github.com/BenLorantfy/nestjs-zod): each DTO is a `z.object({...})` transformed into a class with `createZodDto(schema)` and globally validated by `ZodValidationPipe`. During bootstrap, `patchNestJsSwagger()` teaches Swagger to read these schemas automatically, so validation (Zod) and documentation (`@ApiProperty`) do not need to be duplicated as they would with `class-validator`. Exported schemas (for example, `createUserSchema`) can also be reused and combined (such as `updateUserSchema`, which is simply `createUserSchema.partial()`).
+
+- 🪵 **Observability** — structured logs with Pino, health checks (`/health`), and Prometheus metrics (`/metrics`)
+
+The seed creates three test accounts, one for each role:
+
+| Email | Password | Role |
+|---|---|---|
+| `admin@nestforge.dev` | `admin123` | ADMIN |
+| `manager@nestforge.dev` | `manager123` | MANAGER |
+| `user@nestforge.dev` | `user1234` | USER |
+
+## 📈 Observability
+
+`GET /health` returns the aggregated status of the API — database (TypeORM), Redis, memory (heap/RSS), and disk space — using `@nestjs/terminus`. Each check appears individually in the response, making it clear which component failed.
+
+`GET /metrics` exposes Prometheus-format metrics through `prom-client`: standard Node.js metrics (CPU, memory, event loop), plus `http_request_duration_seconds` (histogram) and `http_requests_total` (counter), both with `method`, `route`, and `status_code` labels. Simply point a Prometheus scrape job at this route.
+
+## 🧪 Tests
+
+```bash
+npm run test          # unit tests
+npm run test:e2e      # integration tests (E2E)
+npm run test:cov      # coverage
+```
+
+E2E tests (`test/*.e2e-spec.ts`) start the real application (Nest + TypeORM + Redis) and call its endpoints with `supertest`, using an isolated database (`.env.test`, the `nestforge_test` database — never the development database). Before running them for the first time:
+
+```bash
+createdb nestforge_test   # or: psql -U nestforge -c "CREATE DATABASE nestforge_test;"
+docker compose up -d postgres redis
+npm run test:e2e
+```
+
+The `pretest:e2e` script automatically applies migrations to this database before every run. Each test cleans the tables before running (`test/utils/clean-database.ts`), so nothing needs to be reset manually between runs. Current coverage includes the complete authentication flow (registration, login, refresh, logout, duplicate email, invalid credentials) and user CRUD with RBAC (ADMIN can do everything, USER can read but cannot create, `/users/me`, and access without a token).
+
+Unit tests (`src/**/*.spec.ts`) run in isolation with the TypeORM repositories and `ioredis` mocked (`vi.fn()` / `vi.mock()`), so they do not require a real database or Redis. Current coverage includes `AuthService` (registration/login), `UsersService` (complete CRUD + pagination + confirmation through `instanceToPlain` that `passwordHash` is not leaked during serialization), `RolesGuard`, `PermissionsGuard`, and health indicators (`TypeOrmHealthIndicator`, `RedisHealthIndicator`).
+
+## 📚 Additional documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — how the project is organized and why certain design decisions were made (Zod vs. class-validator, code-based vs. database-based permissions, BullMQ, etc.)
+- [TESTING.md](TESTING.md) — how to validate migrations, build, unit tests, and E2E tests
+- [docs/adding-a-module.md](docs/adding-a-module.md) — step-by-step instructions for adding a new feature according to the project's conventions
+
+## 🤝 Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete guide.
+
+## 📄 License
+
+This project is licensed under the MIT License — see [LICENSE](LICENSE).
+
+---
+
+Made by [Jeiel Alves](https://github.com/jeiel2013) · [jeieldev.com.br](https://jeieldev.com.br)