nestforge-generator 0.1.0

package/templates/drizzle/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/drizzle/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/drizzle/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/drizzle/README.md

@@ -0,0 +1,257 @@
+# NestForge
+
+**English** | [Português](README.pt-BR.md)
+
+> Production-ready NestJS starter with Drizzle ORM, 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, Drizzle-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** — Drizzle ORM 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 / Query Builder | Drizzle ORM |
+| 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/      # Drizzle connection, schemas, 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 and the services selected during generation, such as PostgreSQL or MySQL, Redis, and Mailpit. SQLite projects do not require a database container.
+
+### Running locally
+
+```bash
+npm install
+cp .env.example .env
+npm run migration:generate
+npm run migration:migrate
+npm run seed
+npm run start:dev
+```
+
+Drizzle Kit reads `drizzle.config.ts`, generates SQL migrations in `drizzle/`, and uses only the schema for the database selected during project generation.
+
+Swagger documentation is available at `http://localhost:3000/docs`.
+
+## 🗺️ 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 `sessions` table. `DrizzleSessionStore` integrates `express-session` with the selected database without depending on Prisma- or TypeORM-specific stores. 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, Redis, memory (heap/RSS), and disk space — using `@nestjs/terminus`. `DrizzleHealthIndicator` queries the selected database's native client, and each check appears individually in the response.
+
+`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 with NestJS and Drizzle and make requests with `supertest`, using the isolated database defined in `.env.test`. Before the first run, generate the migrations:
+
+```bash
+npm run drizzle:generate
+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 Drizzle instance and `ioredis` mocked through `vi.fn()` and `vi.mock()`. They do not require a real database or Redis. Coverage includes `AuthService`, `UsersService`, `RolesGuard`, `PermissionsGuard`, `DrizzleHealthIndicator`, and `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)

package/templates/drizzle/README.pt-BR.md

@@ -0,0 +1,257 @@
+# NestForge
+
+[English](README.md) | **Português**
+
+> Production-ready NestJS starter with Drizzle ORM, 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 é um boilerplate de NestJS pensado para acelerar o início de projetos backend sérios, com autenticação completa, arquitetura limpa, segurança e observabilidade já configuradas. A ideia é você clonar, rodar `docker compose up` e já ter uma API pronta para evoluir.
+
+## ✨ Features
+
+- 🔐 **Autenticação configurável** — JWT com access/refresh token, Session/Cookies persistida com Drizzle, OAuth-only ou nenhuma autenticação
+- 🌐 **OAuth** — Google e GitHub, integrado à estratégia de token ou sessão escolhida
+- 👥 **RBAC** — Roles (Admin, Manager, User) e Permissions granulares
+- 🛡️ **Segurança** — Helmet, CORS, Rate Limiting, validação e serialização com Zod
+- 🗄️ **Banco de dados** — Drizzle ORM com PostgreSQL, MySQL ou SQLite
+- 📨 **E-mails** — filas com BullMQ + Redis, testado localmente com Mailpit
+- 📄 **Documentação automática** — Swagger
+- 🪵 **Logs estruturados** — Pino
+- ✅ **Testes** — unitários e de integração com Vitest
+- 🐳 **Docker** — ambiente completo com um comando
+- ⚙️ **CI/CD** — GitHub Actions (build, lint, test)
+
+## 🧱 Stack
+
+| Camada | Tecnologia |
+|---|---|
+| Framework | NestJS + TypeScript |
+| ORM / Query Builder | Drizzle ORM |
+| Banco | PostgreSQL, MySQL ou SQLite |
+| Cache / Filas | Redis + BullMQ |
+| Autenticação | JWT, Session/Cookies ou OAuth com Passport |
+| Validação | Zod + nestjs-zod (schemas viram DTO + Swagger automaticamente) |
+| Docs | Swagger |
+| E-mail (dev) | Mailpit |
+| Testes | Vitest |
+| CI | GitHub Actions |
+
+## 📁 Estrutura de pastas
+
+```
+src/
+│
+├── auth/          # login, sessões/tokens, OAuth, guards e strategies
+├── users/         # CRUD de usuários
+├── common/        # decorators, filters, guards, interceptors, pipes, utils
+├── config/        # configuração tipada e validada (env)
+├── database/      # conexão Drizzle, schemas, configuração, migrations e seed
+├── modules/       # módulos de domínio adicionais
+├── shared/        # código compartilhado entre módulos
+├── jobs/          # filas e workers (BullMQ)
+├── mail/          # templates e envio de e-mail
+└── main.ts
+```
+
+## 🚀 Começando
+
+### Pré-requisitos
+
+- Node.js 20+
+- Docker e Docker Compose
+
+### Rodando com Docker (recomendado)
+
+```bash
+git clone https://github.com/jeiel2013/nestforge.git
+cd nestforge
+cp .env.example .env
+docker compose up
+```
+
+Isso sobe a API e os serviços escolhidos durante a geração, como PostgreSQL ou MySQL, Redis e Mailpit. Projetos SQLite não precisam de um container de banco.
+
+### Rodando localmente
+
+```bash
+npm install
+cp .env.example .env
+npm run migration:generate
+npm run migration:migrate
+npm run seed
+npm run start:dev
+```
+
+O Drizzle Kit lê `drizzle.config.ts`, gera as migrations SQL em `drizzle/` e usa apenas o schema correspondente ao banco escolhido durante a geração do projeto.
+
+A documentação Swagger fica disponível em `http://localhost:3000/docs`.
+
+## 🗺️ Roadmap
+
+- [x] Autenticação por JWT
+- [x] Autenticação por Session/Cookies
+- [x] OAuth Google/GitHub
+- [x] Estratégia OAuth-only
+- [x] Geração sem autenticação
+- [x] Refresh Token
+- [x] Docker
+- [x] CI (build, lint, test)
+- [x] OAuth (Google/GitHub)
+- [x] Upload de arquivos
+- [x] Filas (BullMQ)
+- [x] E-mails transacionais
+- [x] RBAC completo (permissions granulares)
+- [x] Testes de integração completos
+- [x] Documentação completa (Swagger + guia de arquitetura)
+
+Veja o [ROADMAP.pt-BR.md](ROADMAP.pt-BR.md) detalhado.
+
+### Configurando o login social (OAuth)
+
+Para habilitar login via Google e GitHub, crie um OAuth App em cada provedor e preencha no `.env`:
+
+```bash
+APP_URL=http://localhost:3000
+
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+```
+
+- **Google**: crie as credenciais no [Google Cloud Console](https://console.cloud.google.com/apis/credentials) e configure a URL de callback como `{APP_URL}/auth/google/callback`.
+- **GitHub**: crie um OAuth App em `Settings > Developer settings > OAuth Apps` e configure a mesma URL de callback, trocando para `{APP_URL}/auth/github/callback`.
+
+Depois é só acessar `GET /auth/google` ou `GET /auth/github`. No callback, a API emite access/refresh tokens ou estabelece uma sessão por cookie, conforme a estratégia escolhida. Se for o primeiro acesso, uma conta é criada e vinculada ao provedor.
+
+### Autenticação por Session/Cookies
+
+Quando o projeto é gerado com Session/Cookies, cadastro e login criam uma sessão persistida na tabela `sessions`. O `DrizzleSessionStore` integra o `express-session` ao banco escolhido sem depender de stores específicos do Prisma ou TypeORM. O identificador é enviado no cookie `nestforge.sid`, configurado com `httpOnly`, `sameSite=lax` e `secure` em produção.
+
+Configure no `.env`:
+
+```bash
+SESSION_SECRET=use-um-segredo-com-pelo-menos-32-caracteres
+SESSION_MAX_AGE=604800000
+```
+
+### Recuperação de senha e verificação de e-mail
+
+Todo cadastro (`POST /auth/register`) já dispara um e-mail de verificação automaticamente. Os e-mails são enfileirados com BullMQ/Redis e processados por um worker que envia via SMTP — em desenvolvimento, tudo cai no Mailpit (`http://localhost:8025`), então nada sai pra internet de verdade.
+
+| Rota | O que faz |
+|---|---|
+| `POST /auth/forgot-password` | Recebe um `email` e enfileira o envio do link de redefinição (resposta sempre genérica, não revela se o e-mail existe) |
+| `POST /auth/reset-password` | Recebe `token` + `password` e troca a senha; também revoga os refresh tokens ativos do usuário |
+| `GET /auth/verify-email?token=...` | Confirma o e-mail a partir do link recebido |
+
+Os tokens de reset e verificação expiram em 1 hora e 24 horas, respectivamente, e são de uso único.
+
+## 🔑 Roles & Permissions
+
+| Role | Descrição |
+|---|---|
+| `ADMIN` | acesso total ao sistema |
+| `MANAGER` | gerencia usuários e relatórios |
+| `USER` | acesso padrão |
+
+Cada role tem um conjunto fixo de permissões, mapeado em `src/common/constants/role-permissions.ts`:
+
+| Permission | ADMIN | MANAGER | USER |
+|---|:---:|:---:|:---:|
+| `user:create` | ✅ | ❌ | ❌ |
+| `user:read` | ✅ | ✅ | ✅ |
+| `user:update` | ✅ | ✅ | ❌ |
+| `user:delete` | ✅ | ❌ | ❌ |
+| `report:read` | ✅ | ✅ | ❌ |
+
+Nas rotas, use `@Permissions(Permission.UserCreate)` para exigir uma permissão específica, ou `@Roles(Role.ADMIN)` quando o controle por cargo já for suficiente. Os dois guards (`RolesGuard` e `PermissionsGuard`) rodam globalmente e só bloqueiam a rota se ela tiver o decorator correspondente.
+
+## 👥 Usuários: paginação, filtros e avatar
+
+`GET /users` aceita query params pra paginar e filtrar a listagem:
+
+```bash
+GET /users?page=2&limit=20&search=jeiel&role=ADMIN
+```
+
+| Parâmetro | Descrição |
+|---|---|
+| `page` | página atual (padrão: 1) |
+| `limit` | itens por página, até 100 (padrão: 10) |
+| `search` | busca por nome ou e-mail (case-insensitive) |
+| `role` | filtra por `ADMIN`, `MANAGER` ou `USER` |
+
+A resposta vem no formato `{ data, meta: { total, page, limit, totalPages } }`.
+
+Pra trocar o avatar do usuário autenticado:
+
+```bash
+curl -X POST http://localhost:3000/users/me/avatar \
+  -H "Authorization: Bearer <accessToken>" \
+  -F "file=@/caminho/da/foto.png"
+```
+
+Aceita PNG, JPEG e WEBP até 2MB; o arquivo fica salvo em `./uploads/avatars` e é servido em `/uploads/avatars/<arquivo>`.
+
+## 🛡️ Segurança: serialização e CSRF
+
+Toda validação de entrada (`body`, `query`) usa **Zod** via [`nestjs-zod`](https://github.com/BenLorantfy/nestjs-zod): cada DTO é um `z.object({...})` transformado em classe com `createZodDto(schema)`, validado globalmente pelo `ZodValidationPipe`. O `patchNestJsSwagger()` no bootstrap ensina o Swagger a ler esses schemas automaticamente — não precisa duplicar validação (Zod) e documentação (`@ApiProperty`) como no `class-validator`. Os schemas exportados (ex.: `createUserSchema`) também podem ser reaproveitados/combinados (como o `updateUserSchema`, que é só um `createUserSchema.partial()`).
+
+- 🪵 **Observabilidade** — logs estruturados com Pino, health checks (`/health`) e métricas Prometheus (`/metrics`)
+
+O seed cria três contas de teste, uma por role:
+
+| E-mail | Senha | Role |
+|---|---|---|
+| `admin@nestforge.dev` | `admin123` | ADMIN |
+| `manager@nestforge.dev` | `manager123` | MANAGER |
+| `user@nestforge.dev` | `user1234` | USER |
+
+## 📈 Observabilidade
+
+`GET /health` retorna o status agregado da API — banco, Redis, memória (heap/RSS) e espaço em disco — usando `@nestjs/terminus`. O `DrizzleHealthIndicator` consulta o cliente nativo do banco selecionado e cada verificação aparece individualmente na resposta.
+
+`GET /metrics` expõe métricas no formato do Prometheus (via `prom-client`): as métricas padrão de Node.js (CPU, memória, event loop) mais `http_request_duration_seconds` (histograma) e `http_requests_total` (contador), ambas com labels de `method`, `route` e `status_code`. Basta apontar um scrape job do Prometheus pra essa rota.
+
+## 🧪 Testes
+
+```bash
+npm run test          # unitários
+npm run test:e2e      # integração (e2e)
+npm run test:cov      # cobertura
+```
+
+Os testes e2e (`test/*.e2e-spec.ts`) sobem a aplicação real com NestJS e Drizzle e executam requisições com `supertest`, usando o banco isolado definido em `.env.test`. Antes da primeira execução, gere as migrations:
+
+```bash
+npm run drizzle:generate
+npm run test:e2e
+```
+
+O script `pretest:e2e` já aplica as migrations nesse banco automaticamente antes de cada rodada. Cada teste limpa as tabelas antes de rodar (`test/utils/clean-database.ts`), então não precisa zerar nada manualmente entre execuções. Hoje cobrem o fluxo de autenticação completo (registro, login, refresh, logout, e-mail duplicado, credenciais inválidas) e o CRUD de usuários com RBAC (ADMIN consegue tudo, USER lê mas não cria, `/users/me`, acesso sem token).
+
+Os testes unitários (`src/**/*.spec.ts`) rodam isolados, com a instância do Drizzle e o `ioredis` simulados com `vi.fn()` e `vi.mock()`. Eles não dependem de banco ou Redis reais. A cobertura inclui `AuthService`, `UsersService`, `RolesGuard`, `PermissionsGuard`, `DrizzleHealthIndicator` e `RedisHealthIndicator`.
+
+## 📚 Documentação adicional
+
+- [ARCHITECTURE.pt-BR.md](ARCHITECTURE.pt-BR.md) — como o projeto é organizado e por que certas decisões de design foram tomadas (Zod vs. class-validator, permissions em código vs. banco, BullMQ, etc.)
+- [TESTING.pt-BR.md](TESTING.pt-BR.md) — como validar migrations, build, testes unitários e testes E2E
+- [docs/adding-a-module.md](docs/adding-a-module.md) — passo a passo pra adicionar um recurso novo seguindo as convenções do projeto
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Veja o [CONTRIBUTING.pt-BR.md](CONTRIBUTING.pt-BR.md) para o guia completo.
+
+## 📄 Licença
+
+Este projeto está sob a licença MIT — veja [LICENSE](LICENSE).
+
+---
+
+Feito por [Jeiel Alves](https://github.com/jeiel2013) · [jeieldev.com.br](https://jeieldev.com.br)