# Arquitectura backend

> Estado: **NORMATIVO**. Esta es la fuente de verdad de la arquitectura general del backend.

## Stack y principios

El backend usa Node.js, TypeScript, Express, MariaDB, Sequelize v6, Zod v4, PNPM y Turborepo. Las versiones soportadas se consultan en el `package.json` raíz y en los paquetes del workspace.

Se aplica DDD pragmático y Clean Architecture sin convertir cada principio en una capa adicional. Las decisiones favorecen SOLID, KISS, YAGNI, SSOT, fail fast, programación defensiva y claridad semántica antes que abstracciones prematuras.

`Result` representa fallos esperables; `Maybe` representa ausencia semántica. Las excepciones no son el flujo normal de validación.

## Capas y dirección de dependencias

```text
Infrastructure → Application → Domain
```

- **Domain** no conoce Application ni Infrastructure. Contiene agregados, entidades, Value Objects e invariantes.
- **Application** conoce Domain, Core y contratos necesarios. Orquesta casos de uso y servicios, pero no conoce Express, Sequelize ni modelos ORM.
- **Infrastructure** implementa puertos y contiene HTTP, Sequelize, mappers de persistencia y composition roots.
- **common** contiene contratos compartibles entre backend y web, especialmente DTOs de API. No es una vía para filtrar infraestructura.

Quedan prohibidas las dependencias en dirección inversa, en especial `Application → Infrastructure`.

## Responsabilidades de aplicación e infraestructura

Los casos de uso orquestan, gestionan transacciones cuando corresponde, delegan en servicios y devuelven `Result`. No contienen lógica HTTP ni acceden a Sequelize directamente.

Los repositorios pertenecen a Infrastructure, gestionan una responsabilidad o agregado concreto y usan mappers de persistencia. Un mapper de persistencia bidireccional expone típicamente `toPersistence()` y `toDomain()`; Infrastructure reconstruye con `rehydrate()`. La creación funcional se realiza con `create()` y valida invariantes.

Los builders de salida materializan contratos definidos por schemas Zod. Son deterministas, no acceden a repositorios y pueden convertir Value Objects a primitivas o `Maybe` a `null`.

## Referencias normativas relacionadas

- [Inyección de dependencias](./dependency-injection.md)
- [Flujo HTTP y entrada a Application](./http-request-flow.md)
- [DTOs y schemas](./dto-guidelines.md)
- [Límites entre módulos](./module-boundaries.md)
- [Pruebas backend](./testing-guidelines.md)