De Boilerplate a Producción: Construyendo mi Clean Architecture .NET API Template

Crear un API lista para producción no debería significar empezar desde 0 siempre. En este post, explicaré el diseño y estructura de mi API template de Clean Architecture .NET, qué me motivó a hacerlo, y cómo usarlo para tener una implementación sin sacrificar tiempo y mantenibilidad.

¿Por qué hice este Template?

Al iniciar un proyecto en .NET, suele perderse mucho tiempo en la configuración inicial y en la instalación de dependencias esenciales para que la aplicación funcione correctamente. Esto incluye aspectos como la configuración de la conexión a la base de datos, la documentación con Swagger, las abstracciones de entidades y servicios, entre otros.

Por esa razón, decidí crear este template con lo indispensable para comenzar rápidamente el desarrollo de una API REST siguiendo los principios de Clean Architecture.

¿Qué incluye?

Este template reúne los bloques fundamentales necesarios para iniciar una API .NET lista para producción, con una estructura limpia y mantenible. Incluye una arquitectura por capas con una separación clara de responsabilidades entre Domain, Application, Infrastructure y Presentation.Api.

También implementa CQRS para organizar commands y queries de una forma más escalable, junto con un enfoque unificado para el manejo de resultados y errores, lo que permite respuestas consistentes en toda la aplicación. Además, incorpora validación con FluentValidation, inyección de dependencias mediante métodos de extensión, funcionalidades de autenticación y autorización, envío de correos con plantillas, y persistencia con EF Core y PostgreSQL. Además viene con el Dokerfile y Docker compose pre-configurado, listo para desplegar.

Project structure

Solution layout

Este repositorio contiene los siguientes proyectos, a nivel general:

• CleanArchTemplate.Domain
• CleanArchTemplate.Application
• CleanArchTemplate.Infrastructure
• CleanArchTemplate.SharedKernel
• CleanArchTemplate.Presentation.Api (startup project)

Y el archivo solution:

• CleanArchTemplate.sln

Estructura del proyecto (donde poner que)

CleanArchTemplate.Domain

Qué es: El núcleo del sistema.
Qué va aquí:

• Entities / Aggregates
• Value Objects
• Domain Events
• Domain services (pura lógica de negocio)
• Business rules/invariants

Notas:

• Evita dependencias de ASP.NET Core, EF Core o cualquier librería externa que interactúe con el mundo exterior.
• Este proyecto debe ser el más estable a lo largo del tiempo.

CleanArchTemplate.Application

Qué es: Casos de uso y orquestación de la aplicación.
Qué va aquí:

• Casos de uso / Servicios de la aplicación (commands/queries - CQRS)
• Validaciones y flujos del negocio que interactúan con los objetos del dominio

CleanArchTemplate.Infrastructure

Qué es: Detalles de implementación e integraciones.
Qué va aquí:

• EF Core DbContext, mappings, configurations
• Clientes de servicios externos (message brokers, file storage, etc.)

Notas:

• Esta capa depende de Application y Domain.
• Aquí es donde viven las preocupaciones del “mundo real”.

CleanArchTemplate.Presentation.Api (Startup Project)

Qué es: La capa de entrada HTTP de la API (ASP.NET Core).
Qué va aquí:

• Controladores
• Configuración de la API (DI wiring, middleware, Swagger, auth, etc.)

Notas:

• Este proyecto es el punto de entrada de la aplicación y es el startup project.

CleanArchTemplate.SharedKernel

Qué es: Bloques compartidos y transversales utilizados entre capas.

¿Cómo usarlo?

Correr el proyecto

Opción A — Correr con Docker Compose (Recomendado)

Este repositorio incluye un compose.yaml que inicia:

• API container (expone el puerto 8080)
• PostgreSQL container (expone el puerto 5432)

Start:

docker compose up --build

API URL:

• http://localhost:8080

Base de datos (de compose.yaml):

Nota: dentro de la red de Docker, la API usa Host=db en su cadena de conexión.

Stop:

docker compose down

Stop + remove volumes (deletes local DB data):

docker compose down -v

Opción B — Correr con dotnet run

Prerequisitos:

• .NET SDK instalado
• Una instacia de PostgreSQL (puedes usar Docker para la BD si quieres)

1) Levantar solo la BD por Docker (opcional):

docker compose up -d db

2) Levantar la API (startup project): Desde la raíz del repo:

dotnet run --project CleanArchTemplate.Presentation.Api

Para las variables de entorno y connection strings, setealos en tu shell, appsettings o user secrets como convenga.

Migraciones de Entity Framework Core

Las migraciones están en Infrastructure, pero debe correrse usando la API como el startup project.

Agregar una migración

dotnet ef migrations add <NameOfMigration> --startup-project CleanArchTemplate.Presentation.Api --project CleanArchTemplate.Infrastructure

Aplicar una migración (database update)

dotnet ef database update --startup-project CleanArchTemplate.Presentation.Api --project CleanArchTemplate.Infrastructure

Típico flujo de trabajo para agregar un nuevo feature

1. Domain: crear/actualizar entities, value objects
2. Application: agregar casos de uso (command/query), interfaces necesarias
3. Infrastructure: implementar persistencia o integraciones (EF Core, external APIs)
4. Presentation: exponer caso de uso vía HTTP endpoint/controller

¿Qué mejoraría o agregaría?

• Migrar a OAuth 2.0
• Agregar servicios de exportación a PDF y Excel
• Agregar AutoMapper
• Agregar implementación de MinIO (S3)
• Agregar implementación de Redis

Pensamientos Finales

Este template es el resultado de muchas pequeñas decisiones guiadas por necesidades reales de proyectos. Con el tiempo, me di cuenta de que contar con un punto de partida bien estructurado marca una gran diferencia tanto en velocidad como en calidad.
En lugar de reinventar la misma base en cada proyecto, prefiero comenzar con algo que ya refleje buenas prácticas de arquitectura y que pueda crecer junto con la aplicación.

Siéntete libre de contribuir al proyecto

Repo de Github