Hexagonal API

Template de API Node.js construída com NestJS, estruturada em arquitetura hexagonal (Ports & Adapters). Este repositório foi desenhado para servir como modelo de implementação, com camadas bem definidas e exemplos práticos para acelerar novos projetos.

A documentação Swagger está disponível em /docs quando a aplicação está em execução.

Visão Geral

• Arquitetura hexagonal com separação clara entre domínio, aplicação, infraestrutura e apresentação.
• Suporte a MongoDB e PostgreSQL (via Mongoose e TypeORM).
• Autenticação JWT, validações com class-validator e documentação com Swagger.
• Pronta para desenvolvimento local com Docker Compose (Mongo e Postgres).

Tecnologias

• NestJS 11
• TypeScript
• Swagger/OpenAPI
• Mongoose (MongoDB)
• TypeORM (PostgreSQL)
• Jest (unit e e2e)
• ESLint + Prettier

Arquitetura Hexagonal (Ports & Adapters)

• domain (núcleo):
  • Entidades e regras de negócio.
  • Interfaces/ports (ex.: IUserRepository, IUserService).
• application (casos de uso):
  • Orquestra fluxos de negócio, usa ports para acessar o domínio.
  • DTOs e lógica específica de aplicação.
• infra (adapters):
  • Implementações concretas de ports (repositórios, provedores, banco de dados, e-mail, etc.).
  • Configurações de Mongoose/TypeORM, middleware e providers.
• presentation (interface):
  • Controllers HTTP, DTOs de entrada/saída, filtros de exceção.
  • Integração com Swagger.

Fluxo resumido: Controller → Caso de Uso (application) → Port (domain) → Adapter (infra) → Persistência/Serviços externos.

Estrutura do Projeto

src/
  app.module.ts
  application/
  domain/
  infra/
    database/
    middleware/
    providers/
    repositories/
  presentation/
    controllers/
    dto/
    exceptions/
    helpers/

Como usar este template

• Crie suas entidades e interfaces em src/domain.
• Implemente casos de uso em src/application consumindo interfaces do domínio.
• Crie adapters em src/infra que implementem as interfaces (ex.: repositórios TypeORM, Mongoose, serviços de e-mail, etc.).
• Exponha endpoints em src/presentation/controllers, documente com @nestjs/swagger.

Instalação

npm install

Configuração

• Crie um arquivo .env baseado em example.env com variáveis como:
  • PORT=3333
  • DATABASE_URL (MongoDB) ou defina POSTGRES_* (PostgreSQL)
  • JWT_SECRET, JWT_EXPIRATION, JWT_EXPIRATION_REFRESH
  • EMAIL_HOST, EMAIL_PORT, EMAIL_USER, EMAIL_PASSWORD (opcional)
  • CLOUDINARY_URL (opcional)

Execução

# desenvolvimento
npm run start:dev

# produção (após build)
npm run start:prod

Docker (opcional)

# Subir serviços de desenvolvimento (API + Mongo + Postgres)
npm run docker:dev

# Subir serviços de produção (API)
npm run docker:prod

Banco de Dados

• Pré-requisitos: Docker Desktop instalado e em execução.
• Serviços disponíveis: postgres e mongo definidos em docker-compose.yml (profile development).

Postgres (Docker)

# Subir apenas o Postgres
docker compose --profile development up -d postgres

# Ver logs (opcional)
docker compose logs -f postgres

• Conexão (local): postgresql://hexagonal:hexagonal@localhost:5432/hexagonal
• Variáveis sugeridas:
  • POSTGRES_HOST=localhost
  • POSTGRES_PORT=5432
  • POSTGRES_USER=hexagonal
  • POSTGRES_PASSWORD=hexagonal
  • POSTGRES_DB=hexagonal

MongoDB (Docker)

# Subir apenas o MongoDB
docker compose --profile development up -d mongo

# Ver logs (opcional)
docker compose logs -f mongo

• Conexão (local): mongodb://admin:prisma@localhost:27017/db?retryWrites=true&connectTimeoutMS=10000&authSource=admin&authMechanism=SCRAM-SHA-1
• Variáveis sugeridas:
  • DATABASE_URL=mongodb://admin:prisma@localhost:27017/db?retryWrites=true&connectTimeoutMS=10000&authSource=admin&authMechanism=SCRAM-SHA-1

Parar serviços

# Derrubar apenas os serviços de banco
docker compose --profile development down

• Para subir tudo (API + bancos), use npm run docker:dev.

Autor

• Liniker Silva — contato@liniker.com.br

Documentação (Swagger)

• Acesse http://localhost:3333/docs
• Baixar YAML: http://localhost:3333/swagger/yaml
• Baixar JSON: http://localhost:3333/swagger/json

Scripts úteis

• npm run test → testa unidade
• npm run test:e2e → testa integração/e2e
• npm run lint → ajuste de lint
• npm run format → formata código
• npm run seed → executa seeds em mock/seed.ts
• npm run docs → exporta Swagger para swagger.yaml

Padrões e Boas Práticas

• Validar entradas com class-validator e pipes globais.
• Documentar DTOs e controllers com @nestjs/swagger.
• Não acoplar regra de negócio a frameworks; mantenha no domain.
• Acesso a dados via ports (interfaces) e adapters concretos.

Modelo Operacional

• Este repositório acompanha o arquivo modelo.txt com o desenho de um modelo híbrido de operação (Guia Digital). Use como referência para estruturar perfis, fluxos e requisitos.

Licença

• Licença atual: UNLICENSED. Ajuste conforme a necessidade do seu projeto.