# Koala Nest

> A facilitator for building NestJS APIs with DDD architecture. The CLI copies ready-made modules into your project — code you can read, adapt, and maintain.

Documentation optimized for LLMs. Each topic links to the corresponding Markdown file — no duplicated content.

## Introduction

- [Overview](markdown/en/intro/overview.md): What Koala Nest is and how it fits into NestJS projects with DDD.
- [DDD Architecture](markdown/en/intro/ddd-architecture.md): Koala Nest layers and how a request flows through the system.

## Getting Started

- [Installation guide](markdown/en/getting-started/installation-guide.md): Install the CLI and create your first NestJS project with DDD.
- [Environment variables](markdown/en/getting-started/environment-variables.md): Environment variable configuration and validation with Zod.
- [Project structure](markdown/en/getting-started/project-structure.md): Application bootstrap, main modules, and entry point.

## Core

- [Reusable bases](markdown/en/core/reusable-bases.md): Base classes for handlers, validators, controllers, and repositories.
- [Cache (Redis)](markdown/en/core/cache.md): Data caching with ICacheService — Redis in production or local memory in dev.
- [ObjectClass](markdown/en/core/object-class.md): Utility class for requests, responses, and entities with the from() factory.
- [Pagination and filters](markdown/en/core/pagination.md): Pagination, sorting, and filters in listings with PaginationRequest and PaginationDto.
- [Cron and Event Jobs](markdown/en/core/cron-event-jobs.md): Scheduled background jobs (CronJob) and domain event processing (EventJob).
- [Koala Utils](markdown/en/core/koala-utils.md): Integration with @koalarx/utils — delay, CPF/CNPJ, strings, dates, and arrays.

## Domain

- [Entities](markdown/en/domain/entities.md): TypeORM entity modeling with EntityBase and the AutoMap decorator.
- [Repository contracts](markdown/en/domain/repository-contracts.md): Abstract repository classes and query DTOs in the domain.

## Application

- [Handlers](markdown/en/application/handlers.md): Use cases in the application layer with RequestHandlerBase.
- [Validators](markdown/en/application/validators.md): Input validation with RequestValidatorBase and Zod schemas.
- [Requests and responses](markdown/en/application/requests-responses.md): Input and output DTOs with ObjectClass, AutoMap, and Swagger decorators.
- [Mapping system](markdown/en/application/mapping.md): AutoMap, createMap, AutoMapper, and mapping registration between classes.

## Host

- [HTTP middleware](markdown/en/host/http-middleware.md): CORS, cookies, rate limit, and HTTP bootstrap via applyHttpMiddleware.
- [Controllers](markdown/en/host/controllers.md): Thin HTTP controllers that delegate to handlers.
- [Routes and tags](markdown/en/host/routes.md): Centralized route configuration with RouterConfigBase.
- [Error handling](markdown/en/host/error-handling.md): Global ErrorsFilter for Zod, TypeORM, and internal errors.
- [Authentication](markdown/en/host/authentication.md): JWT, global guards, public routes, and generic OAuth2.
- [OpenAPI documentation with Scalar](markdown/en/host/openapi-scalar.md): How to configure and customize interactive documentation at /doc with Scalar (OpenAPI via @nestjs/swagger).
- [Health check](markdown/en/host/health-check.md): GET /health endpoint with NestJS Terminus — database and optional Redis.

## Infra

- [Database](markdown/en/infra/database.md): TypeORM configuration with PostgreSQL via DatabaseModule and DataSource factory.
- [TypeORM repositories](markdown/en/infra/repositories.md): Concrete repository implementation extending RepositoryBase.
- [Migrations](markdown/en/infra/migrations.md): TypeORM migration generation and execution in Koala Nest.

## Guides

- [Person CRUD flow](markdown/en/guides/person-crud-flow.md): End-to-end guide to the Person module as a reference for new resources.