# Koala Nest

> Facilitador para criar APIs NestJS com arquitetura DDD. A CLI copia módulos prontos para dentro do projeto — código que você pode ler, adaptar e manter.

Documentação otimizada para LLMs. Cada tópico aponta para o arquivo Markdown correspondente — sem duplicar conteúdo.

## Introdução

- [Visão geral](markdown/pt/intro/visao-geral.md): O que é o Koala Nest e como ele se encaixa em projetos NestJS com DDD.
- [Arquitetura DDD](markdown/pt/intro/arquitetura-ddd.md): Camadas do Koala Nest e como a requisição percorre o sistema.

## Primeiros passos

- [Guia de instalação](markdown/pt/inicio/guia-de-instalacao.md): Instale a CLI e crie seu primeiro projeto NestJS com DDD.
- [Variáveis de ambiente](markdown/pt/inicio/variaveis-de-ambiente.md): Configuração e validação de variáveis de ambiente com Zod.
- [Estrutura do projeto](markdown/pt/inicio/estrutura-do-projeto.md): Bootstrap da aplicação, módulos principais e ponto de entrada.

## Core

- [Bases reutilizáveis](markdown/pt/core/bases-reutilizaveis.md): Classes base para handlers, validators, controllers e repositórios.
- [Cache (Redis)](markdown/pt/core/cache.md): Cache de dados com ICacheService — Redis em produção ou memória local em dev.
- [ObjectClass](markdown/pt/core/object-class.md): Classe utilitária para requests, responses e entidades com factory from().
- [Paginação e filtros](markdown/pt/core/paginacao.md): Paginação, ordenação e filtros em listagens com PaginationRequest e PaginationDto.
- [Cron e Event Jobs](markdown/pt/core/cron-event-jobs.md): Jobs agendados em background (CronJob) e processamento de eventos de domínio (EventJob).
- [Koala Utils](markdown/pt/core/koala-utils.md): Integração com @koalarx/utils — delay, CPF/CNPJ, strings, datas e arrays.

## Domain

- [Entidades](markdown/pt/domain/entidades.md): Modelagem de entidades TypeORM com EntityBase e decorador AutoMap.
- [Contratos de repositório](markdown/pt/domain/contratos-repositorio.md): Classes abstratas de repositório e DTOs de consulta no domínio.

## Application

- [Handlers](markdown/pt/application/handlers.md): Casos de uso na camada application com RequestHandlerBase.
- [Validators](markdown/pt/application/validators.md): Validação de entrada com RequestValidatorBase e schemas Zod.
- [Requests e responses](markdown/pt/application/requests-responses.md): DTOs de entrada e saída com ObjectClass, AutoMap e decoradores Swagger.
- [Sistema de mapeamento](markdown/pt/application/mapeamento.md): AutoMap, createMap, AutoMapper e registro de mapeamentos entre classes.

## Host

- [Middleware HTTP](markdown/pt/host/middleware-http.md): CORS, cookies, rate limit e bootstrap HTTP via applyHttpMiddleware.
- [Controllers](markdown/pt/host/controllers.md): Controllers HTTP finos que delegam para handlers.
- [Rotas e tags](markdown/pt/host/rotas.md): Configuração centralizada de rotas com RouterConfigBase.
- [Tratamento de erros](markdown/pt/host/tratamento-de-erros.md): Filtro global ErrorsFilter para Zod, TypeORM e erros internos.
- [Documentação OpenAPI com Scalar](markdown/pt/host/openapi-scalar.md): Como configurar e personalizar a documentação interativa em /doc com Scalar (OpenAPI via @nestjs/swagger).
- [Autenticação](markdown/pt/host/autenticacao.md): JWT, guards globais, rotas públicas e OAuth2 genérico.
- [Health check](markdown/pt/host/health-check.md): Endpoint GET /health com NestJS Terminus — banco e Redis opcional.

## Infra

- [Banco de dados](markdown/pt/infra/banco-de-dados.md): Configuração TypeORM com PostgreSQL via DatabaseModule e DataSource factory.
- [Repositórios TypeORM](markdown/pt/infra/repositorios.md): Implementação concreta de repositórios estendendo RepositoryBase.
- [Migrations](markdown/pt/infra/migrations.md): Geração e execução de migrations TypeORM no Koala Nest.

## Guias

- [Fluxo CRUD Person](markdown/pt/guias/fluxo-crud-person.md): Guia ponta a ponta do módulo Person como referência para novos recursos.