orquestador/specs/ARCHITECTURE.md

Arquitectura

Un único módulo Maven, paquete raíz com.organizacion.orchestrator. La implementación sigue la especificación; esta entrega establece sus fronteras, no implementa todavía el motor.

Capacidad	Responsabilidad
flow	Borradores, validación, publicación, activación y caché inmutable
request	Instancias, acceso por recurso y eventos disponibles
execution	Comandos idempotentes, cola PostgreSQL, leases, fencing y recuperación
decision	AST tipado y decisiones puras con BigDecimal
action	Registro de handlers y mappings permitidos
integration	Catálogo confiable, HTTP y normalización de contratos
document	Referencias verificadas; sin almacenamiento binario
audit	Historial inmutable y auditoría administrativa
shared	Errores, identidad, reloj y configuración transversal

Cada capacidad crecerá en domain, application, infrastructure y api cuando la tarea lo requiera. Dominio no depende de HTTP/JPA. API usa DTOs separados. Infraestructura implementa puertos. No crear entidades o interfaces ficticias para aparentar completar T04.

Fronteras transaccionales

1. Aceptar un evento en transacción corta: acceso, bloqueo de solicitud, idempotencia, revisión, guardia, ejecución PENDING y auditoría.
2. Worker reclama con SKIP LOCKED y confirma antes de HTTP. Cada acción guarda checkpoint y clave externa estable.
3. Finalizar en transacción: validar lease/token/revisión, aplicar datos/estado y guardar resultado y auditoría atómicamente.

Una sola ejecución activa por solicitud. La incertidumbre de un efecto externo exige conciliación. No prometer exactly-once. Estados de ejecución y negocio son independientes.

Configuración y acceso

Publicación inmutable; instancias fijan flow_id. Activo se resuelve coherentemente en PostgreSQL. JSONB extiende datos; no permite scripts, clases, URLs o credenciales arbitrarios. Cambios de licencia con capacidades existentes no requieren columnas ni condiciones Java específicas.

JWT se valida por firma, expiración, issuer y audiencia. T07 expone administración protegida y T08 creación/consulta de solicitudes. Roles, scope y propiedad se verifican antes de acceder a recursos; ambos grupos de rutas requieren habilitación explícita y runtime DB restringido. Sin entidades abiertas durante llamadas HTTP (open-in-view=false).

Dominio implementado en T04

Consultar modelo y puertos. El dominio y los puertos son Java puro; los records contienen snapshots inmutables. flow/api/ValidationReportResponse es un DTO separado con conversión explícita y prueba contra el esquema REST. Los adapters JPA/HTTP y servicios de aplicación se implementarán en sus tareas; ningún record del dominio es entidad JPA ni se expone automáticamente por REST.

Administración interna de flujos T06

Consultar validación y publicación. FlowAdministration y sus puertos son independientes de infraestructura. PostgresFlowStore implementa el protocolo de locks/auditoría con JDBC transaccional (ADR-010). La exposición de controladores administrativos queda ligada a T07, con autenticación/autorización verificada; los contratos REST existentes no se modifican.

Solicitudes T08

Requests y RequestStore mantienen la frontera pura de aplicación. PostgresRequestStore comparte DataSource/transacción con FlowStore, serializa claves idempotentes en PostgreSQL y confirma solicitud/auditoría/ledger en conjunto. RequestView es un DTO explícito; su consulta usa un snapshot SQL para instancia, flujo fijado y ejecución activa. Configuración de infraestructura común independiente del interruptor admin. Detalles y decisiones: REQUESTS.md, SECURITY.md y ADR-012.

Aceptación de eventos T09

Events/EventStore y EventPolicy conservan aplicación/dominio puros. PostgresEventStore bloquea la solicitud autorizada y confirma ejecución, revisión y auditoría juntas. El replay lee estado actual antes de revisar la revisión esperada; las acciones permanecen sin ejecutar. La definición se obtiene por flow_id fijado, también tras retiro, sin invertir el orden de locks de publicación. Ver EVENTS.md y ADR-013.

Worker T10

WorkerStore separa reclamación, renovación, carga/checkpoints y confirmación atómica. PostgresWorkerStore implementa fencing con tiempo DB. WorkerEngine resuelve mappings, reutiliza decisiones T05 y valida datos finales. WorkerLoop limita concurrencia y renueva durante acciones fuera de transacción. WorkerActions es el puerto para adapters T11; el fallback no inventa resultados. ExecutionController expone una proyección autorizada del estado. V3 conserva effect para recuperación segura. Ver WORKER.md y ADR-014.