Clean Architecture es un patrón arquitectónico muy usado en la industria del software, especialmente en .NET, para construir APIs escalables y mantenibles. Aquí aprendes cómo distribuir responsabilidades en capas y aplicarlo en un proyecto real con cuatro proyectos diferenciados: API, Application, Domain e Infrastructure.

¿Qué es Clean Architecture y por qué importa en .NET?

La arquitectura limpia propone una distribución de responsabilidades muy específica con un objetivo claro: que tu API pueda crecer sin volverse un caos. Si mantienes la estructura, navegar entre componentes se vuelve sencillo aunque el proyecto escale.

El patrón se apoya en separar presentación, lógica de aplicación, dominio e infraestructura. Cada capa tiene un rol y se comunica con las demás siguiendo reglas claras, evitando que la lógica de negocio se mezcle con detalles técnicos como la conexión a base de datos.

¿Qué problema resuelve Clean Architecture? Resuelve el desorden cuando un proyecto crece. Al separar responsabilidades en capas, puedes mantener, escalar y modificar tu API sin romper otras partes del sistema.

¿Cómo se distribuyen las capas en un proyecto .NET?

Llevado a .NET, el patrón se materializa en cuatro proyectos dentro de la misma solución. Cada uno cumple una función específica y referencia solo a los proyectos que necesita.

¿Qué contiene la capa de presentación o API?

El proyecto de API es la cara visible hacia los clientes que consumen el servicio. Aquí vive todo lo que conecta con el mundo exterior.

• Controladores que reciben las peticiones HTTP.
• Configuración general como Swagger para documentación.
• Middleware y autenticación.
• El archivo Program donde se registran los servicios.

Esta capa funciona como la interfaz gráfica de la API. En proyectos web tradicionales sería la UI, pero aquí cumple el mismo rol: exponer funcionalidad al cliente.

¿Qué responsabilidad tiene la capa de Application?

La capa de Application concentra los contratos y la lógica específica de la aplicación. Es donde defines qué se puede hacer, pero no cómo se hace.

• Las interfaces que actúan como contratos entre capas.
• Casos de uso y comportamientos específicos, por ejemplo un cálculo matemático.
• Utilidades que necesite la API.

Un detalle importante: aquí están las interfaces como IUserService o ITaskService, pero no su implementación. Esa responsabilidad le toca a otra capa.

¿Para qué sirven Domain e Infrastructure?

El proyecto de Domain es el más sencillo de todos. Contiene las entidades del negocio, los modelos que representan la información del servidor. En el ejemplo aparecen TaskItem y User como modelos que conectan con la base de datos.

El proyecto de Infrastructure se encarga de la implementación técnica:

• El AppDbContext de Entity Framework para conectarse a la base de datos.
• Las implementaciones reales de los servicios como TaskService y UserService.
• La configuración de dependency injection del contexto y los servicios.
• Conexiones con servicios cloud como Azure o AWS.

Infrastructure referencia a Application para ver los contratos y luego los implementa. Así, si un día cambias de base de datos o de proveedor cloud, solo tocas esta capa sin afectar el resto.

¿Cómo se referencian los proyectos entre sí?

El flujo de dependencias en .NET sigue una jerarquía clara. El proyecto de API referencia a Application, Domain e Infrastructure. Infrastructure referencia a Application para acceder a los contratos.

¿Por qué Infrastructure se registra en Program.cs? Porque ahí se suscriben el DbContext y los servicios mediante dependency injection. Sin esa referencia, la API no sabría cómo resolver las implementaciones reales.

Domain suele referenciarse desde API por practicidad, ya que permite reutilizar las entidades. Sin embargo, no es la mejor práctica.

¿Cómo mejorar la estructura con DTOs y ViewModels?

Exponer entidades de dominio directamente en la API tiene un riesgo: acoplas tu modelo de base de datos a la respuesta pública. Una mejor práctica es crear dentro de Application una carpeta llamada ViewModels o DTOs.

Estas clases representan la respuesta final que verá el cliente, con propiedades y configuración pensadas para el consumo externo, no para el almacenamiento. Infrastructure se encarga de mapear las entidades de dominio a esos DTOs antes de devolver la información a la API.

Con ese cambio puedes eliminar la referencia directa a Domain desde el proyecto de API. El resultado es una separación más estricta y un proyecto más fácil de mantener.

Reto para aplicar lo aprendido

Descarga la rama de clean architecture desde los recursos de la clase y modifica la estructura siguiendo estos pasos:

1. Crea la carpeta ViewModels o DTOs dentro de Application.
2. Define las clases que serán la respuesta final de cada endpoint.
3. Ajusta Infrastructure para que mapee las entidades de Domain a esos DTOs.
4. Elimina la referencia de Domain en el proyecto de API.
5. Ejecuta el proyecto y prueba todos los endpoints para confirmar que funcionan igual.

¿Aplicaste el reto? Cuéntame en los comentarios cómo organizaste tus DTOs y qué cambios notaste al desacoplar Domain de la API.