EleganFlow, casi dos años después: unidad de trabajo híbrida e idempotencia en NestJS
En marzo de 2025 publiqué EleganFlow, la arquitectura modular que uso en mis backends con NestJS. La idea era simple: separar cada caso de uso en verificación (sintaxis y semántica), proceso y presentación, con piezas pe
En marzo de 2025 publiqué EleganFlow, la arquitectura modular que uso en mis backends con NestJS. La idea era simple: separar cada caso de uso en verificación (sintaxis y semántica), proceso y presentación, con piezas pequeñas de una sola responsabilidad.
Desde entonces la he usado en dos backends en producción: uno propio, con decenas de módulos, y uno más grande de una empresa, donde la misma idea de separar verificación y escritura llegó más lejos: hoy gobierna lo que un agente de IA puede escribir en datos reales. Lo cuento más abajo. En los dos, las etapas aguantaron bien. Lo que no aguantó fue una frase de aquel artículo: «si un paso falla, se hace rollback».
Este es el relato de por qué esa frase era una promesa vacía y cómo la cumplí.
Repaso rápido: las cuatro piezas
| Etapa | Qué hace | Pieza en NestJS |
|---|---|---|
| Sintaxis | Estructura y tipos del input | DTO + class-validator y ValidationPipe global |
| Semántica | Reglas de negocio, sin escribir nada | checkers (reglas simples) y rules (cruzan entidades) |
| Proceso | Ejecutar el caso de uso | blueprint que orquesta processes (un paso, una responsabilidad) |
| Presentación | Armar la respuesta, sin escribir | adjust / response |
El flujo: controller (sintaxis) → service (semántica) → blueprint.execute (proceso) → service arma la respuesta (presentación).
El problema: el rollback manual no es rollback
En la versión original, cada process tenía su método para deshacerse. Si el paso 3 fallaba, el blueprint llamaba al rollback del paso 2 y luego al del 1.
Al auditar el código encontré lo que cualquiera que haya intentado esto conoce:
- Casi nadie escribía el rollback. Era opcional, así que en la práctica no existía.
- Muchos blueprints se saltaban los *processes* y escribían directo con el DAO. Esos cambios quedaban fuera de cualquier reversa.
- El rollback manual compite con la concurrencia. Si otra petición modificó el registro entre tu escritura y tu reversa, la reversa pisa su cambio.
- Si el proceso muere a la mitad, no hay código que corra la reversa. Los datos quedan a medias.
La base de datos ya resolvía todo eso desde hace décadas. Se llama transacción.
La decisión: modelo híbrido
La base de datos se revierte con transacción. Lo externo sale después del commit. Solo lo que no puede esperar se compensa.
| Transacción | Compensación manual | |
|---|---|---|
| Todo o nada en la DB | Lo garantiza Postgres | Depende del código de cada rollback |
| Concurrencia | Aislada | La reversa puede pisar cambios ajenos |
| Caída a la mitad | Postgres revierte | Queda a medias |
| Efectos externos (cola, SMS, S3) | No los cubre | Sí |
Ninguna columna gana sola. Por eso es híbrido: transacción para lo que vive en la base de datos, efectos diferidos para lo externo y compensación como último recurso.
1. El blueprint abre una sola transacción
El blueprint deja de escribir. Su único trabajo es correr sus processes dentro de una unidad de trabajo:
// Simplificado
export class CreatePersonBlueprint {
execute(person: Person, idempotency?: IdempotencyOptions) {
return runProcessesInTransaction(
person,
[this.createPersonProcess],
this.dataSource,
idempotency,
);
}
}
2. Cada process recibe un contexto
export interface ProcessContext {
readonly manager: EntityManager; // la transacción
afterCommit(effect: SideEffect): void; // efectos que salen solo si hubo commit
onRollback(compensation: SideEffect): void; // reversa de lo externo ya ocurrido
}
El process escribe con context.manager a través de su DAO. Si cualquier paso falla, Postgres revierte todo y la API responde 409 con el detalle:
{ "isValid": false, "constraints": [...], "rolledBack": true, "rollbackErrors": [] }
3. Lo externo sale después del commit
Encolar un job, emitir un evento o mandar un SMS no se puede revertir con ROLLBACK. Si lo haces dentro de la transacción y luego esta falla, ya avisaste de algo que no existe.
// Simplificado
async process(person: Person, context?: ProcessContext) {
const saved = await this.personDao.create(person, context?.manager);
await runAfterCommit(context, () =>
this.queue.add('person.created', { id: saved.id }),
);
return { success: true, data: saved };
}
runAfterCommit es un helper pequeño: si hay contexto, registra el efecto con context.afterCommit; si el process corre fuera de una transacción, lo ejecuta en ese momento.
Si un efecto falla después del commit, el dato ya está guardado: no se revierte, se reporta en sideEffectErrors y lo resuelven los reintentos de la cola.
4. Compensación solo cuando no hay otra
Hay casos donde lo externo tiene que ocurrir antes: subir un archivo a S3 para guardar su key en la fila. Ahí sí registras una compensación con context.onRollback(...), que corre en orden inverso si la transacción falla. Es la excepción, no la regla.
Idempotencia: que reintentar sea seguro
Con transacciones resolví el «todo o nada». Faltaba el otro clásico: el cliente que no recibe respuesta por un corte de red y reintenta. Sin protección, eso es un registro duplicado.
La solución es el header Idempotency-Key, como lo hacen las APIs de pagos:
- La clave se guarda con un scope
{cuenta}:{modulo}.{operacion}, así la misma clave no choca entre clientes. - Se guarda junto con una huella (sha256 del payload) y la respuesta.
- Se reclama y se completa en la misma transacción del caso de uso. Si la operación se revierte, la clave también, y el cliente puede reintentar limpio.
-
Mismo reintento → se devuelve la respuesta guardada (
replayed: true) sin ejecutar processes ni efectos. -
Misma clave, otros datos →
409 IDEMPOTENCY_KEY_REUSED. -
Dos peticiones simultáneas con la misma clave → Postgres las serializa:
INSERT … ON CONFLICT DO NOTHINGhace esperar a la segunda hasta que la primera termina.
Para las colas apliqué la misma idea con un jobId determinista (acción + id + updatedAt), para que la cola no encole dos veces el mismo trabajo.
Qué cambió de la regla original
Antes la regla era «sin transacciones, consistencia eventual». Ahora es más precisa:
- Dentro de un blueprint: ACID.
- Entre módulos: consistencia eventual con eventos y colas, como siempre.
Anti-patrones que ahora se rechazan en revisión
- Blueprint que escribe con el DAO: queda fuera del rollback y de la idempotencia.
- Encolar, emitir o notificar dentro de la transacción.
-
Process que escribe sin
context.manager. - Abrir una transacción fuera del blueprint (en el service o el DAO).
- Validación semántica dentro del blueprint en vez del service.
Un paso más: evaluar antes de aplicar
En el backend de la empresa, la separación entre verificación y proceso llegó a su caso más delicado: un agente de IA que, desde un chat, completa datos que faltan. El agente no escribe directo. Cada escritura pasa por tres llamadas:
- Resolver. Identifica la entidad dentro de la cuenta y de lo que el usuario puede ver. Si coinciden dos o más, no se escribe nada: se pide aclaración.
-
Evaluar. Es la verificación semántica de EleganFlow expuesta como endpoint, sin escribir nada. Devuelve un veredicto por campo (
AUTO,UNCHANGED,NEEDS_CONFIRMATION,CONFLICToINVALID) con su motivo, y lista los efectos que el cambio tendría en otras entidades. -
Aplicar. Vuelve a evaluar en el momento de escribir, para no pisar un dato que cambió entre la propuesta y la escritura. Escribe la entidad y sus efectos en una sola transacción, y solo si los efectos son los que el usuario confirmó (
effectsKey).
Las reglas que lo hacen seguro:
- Decide el backend, no el modelo. El agente interpreta lo que dice el usuario; el backend decide si un cambio se escribe solo, se pregunta o se rechaza. Las mismas reglas sirven al chat, a la lectura de documentos y a la carga masiva, así que nadie las reimplementa.
- Escritura automática solo con cuatro condiciones: entidad única, campo vacío, valor válido y ningún conflicto. Sobrescribir un valor siempre pide confirmación, y la confirmación sale de una acción del usuario, nunca del modelo.
- Reintentar es seguro. En los flujos con documento, cada petición lleva una clave de idempotencia protegida por un índice único, y cada escritura queda como una fila de historial con su fuente y el texto que confirmó el usuario.
- Lo asíncrono se vuelve durable. Cuando la entrada es un documento que se procesa en segundo plano, el flujo se guarda como una acción con estados, versión, propuesta, confirmación y reconciliación.
Es la misma idea de EleganFlow (verificar sin escribir, procesar en una sola transacción) aplicada a la pregunta que más pesa hoy: ¿cómo dejas que una IA proponga cambios en datos reales sin perder el control?
Por qué una arquitectura definida importa más en la era de la IA
Hoy gran parte del código lo escribe o lo propone un asistente de IA. Eso no hace menos necesaria la arquitectura; la hace más necesaria. No lo digo por intuición; esto es lo que dicen los datos públicos que encontré:
- La IA amplifica lo que ya hay. El reporte DORA 2025 de Google (casi 5,000 profesionales, 90 % usa IA en el trabajo) lo resume así: «AI doesn't fix a team; it amplifies what's already there». Un equipo con bases sólidas mejora; uno sin ellas acelera su desorden.
- Más IA no significa entregas más estables. En DORA 2024, por cada 25 % de aumento en la adopción de IA se estimó una caída de 1.5 % en el ritmo de entrega y de 7.2 % en la estabilidad. El propio reporte lo vincula con no respetar lo básico, como trabajar en lotes pequeños. Es una correlación de encuesta, no una causa probada.
- Se copia más y se refactoriza menos. GitClear analizó 211 millones de líneas cambiadas entre 2020 y 2024: el código «movido» (su indicador de refactorización) bajó de 25 % en 2021 a menos de 10 % en 2024, y el copiado y pegado subió de 8.3 % a 12.3 %. Por primera vez, se copia más de lo que se mueve. El estudio mide la tendencia del periodo en que se extendieron los asistentes; no prueba que cada bloque duplicado lo escribiera una IA.
- «Casi correcto» es el problema principal. En la encuesta de Stack Overflow 2025, 46 % de los desarrolladores desconfía de la precisión de la IA (33 % confía), 66 % señala como su mayor frustración las soluciones «casi correctas, pero no del todo» y 45 % dice que depurar código generado toma más tiempo.
- El código generado no es seguro por defecto. Veracode probó más de 100 modelos en 80 tareas: el código introdujo vulnerabilidades del OWASP Top 10 en 45 % de los casos.
Qué aporta EleganFlow en ese contexto
Esto es mi experiencia, no un estudio. No tengo métricas propias de productividad ni de defectos; describo el mecanismo, no un resultado medido.
-
Un contrato que el agente puede leer. En mi repositorio, las capas, los anti-patrones y la implementación de referencia viven en el
CLAUDE.md, que Claude Code carga en cada sesión según su documentación oficial. El asistente no adivina dónde va cada cosa: hay una respuesta escrita. -
«Casi correcto» se vuelve detectable. Una regla como «un process no escribe sin
context.manager» se revisa en un diff en segundos. Sin arquitectura, la pregunta en revisión es «¿esto está bien?»; con ella, es «¿esto cumple el contrato?». - Reutilizar en lugar de copiar. La transacción, la idempotencia y los efectos tras commit viven en un solo runner. El patrón correcto es llamarlo, no reescribirlo en cada módulo, que es justo la duplicación que reporta GitClear.
- Cambios pequeños por diseño. Un process = una responsabilidad. Eso produce diffs cortos y revisables, que es el «lote pequeño» que DORA señala como base.
- Menos superficie que revisar. Antes había que verificar que cada rollback manual estuviera bien escrito. Ahora la garantía la da Postgres y solo hay que verificar una cosa: que cada escritura pase por la transacción.
Lo que una arquitectura no resuelve
Siendo igual de claro: una arquitectura por capas no hace seguro el código. Una inyección o un XSS pueden vivir perfectamente dentro de un process bien ubicado. Tampoco sustituye la revisión humana ni las pruebas. Lo que hace es reducir el espacio de decisiones que el asistente puede tomar mal y volver más fácil revisar las que toma.
Dónde estoy hoy
Siendo honesto: esto empezó como piloto y sigue acotado. Ya corre en producción en un módulo completo (alta, edición y baja); el resto de los módulos sigue en el modelo anterior. Está verificado con pruebas unitarias y de integración contra un Postgres real: rollback real, reintento sin duplicados, peticiones concurrentes y clave reusada. El frontend todavía no envía el header, así que la idempotencia existe en la API pero aún no la aprovecha ningún cliente.
Lo siguiente es migrar módulo por módulo, empezando por los que más escriben directo con el DAO, y añadir la purga periódica de claves viejas.
Lo que aprendí
La primera versión de EleganFlow ordenaba el código. Esta segunda versión hace que el orden garantice algo. Un rollback que depende de que cada desarrollador lo escriba es una sugerencia; uno que hace la base de datos es un contrato.
Y en un momento en que el código se genera más rápido de lo que se revisa, ese contrato es lo que permite usar IA sin perder el control del sistema.
Si ya usas EleganFlow o una arquitectura parecida, me interesa saber: ¿cómo manejas los efectos externos cuando la transacción falla?
Fuentes
- Google Cloud, Announcing the 2024 DORA report (22-oct-2024): https://cloud.google.com/blog/products/devops-sre/announcing-the-2024-dora-report
- Google Cloud, Announcing the 2025 DORA report (23-sep-2025): https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report
- GitClear, AI Copilot Code Quality: 2025 Look Back: https://www.gitclear.com/ai_assistant_code_quality_2025_research
- Stack Overflow, 2025 Developer Survey — AI: https://survey.stackoverflow.co/2025/ai
- Veracode, comunicado del 2025 GenAI Code Security Report (30-jul-2025): https://www.veracode.com/press-release/ai-generated-code-poses-major-security-risks-in-nearly-half-of-all-development-tasks-veracode-research-reveals/
- Claude Code, Best practices (sección CLAUDE.md): https://code.claude.com/docs/en/best-practices
- Artículo original de EleganFlow (11-mar-2025): https://dev.to/juan_carlosvalderrbano/implementacion-de-eleganflow-arquitectura-modular-y-sostenible-odn
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.