ImagFlow — Motor de Flujos

Proposito

ImagFlow es el motor de orquestacion generico de la plataforma Imagy. Permite disenar, versionar y ejecutar flujos multi-paso que coordinan proveedores externos, aplican reglas de negocio y notifican resultados. Es utilizado por todos los demas dominios cuando necesitan orquestar procesos que involucran validaciones, capturas o integraciones externas.

Responsabilidades

Responsabilidad	Descripcion
Diseno de flujos	CRUD de flujos con pasos, reglas, notificaciones y proveedores
Versionamiento	Ciclo de vida inmutable: draft, published, archived
Templates	Catalogo de flujos reutilizables, duplicacion hacia tenants
Ejecucion	Orquestacion de pasos cuando un usuario final accede al link
Provider Gateway	Comunicacion unificada con proveedores externos (adapters, failover, circuit breaker)
Motor de reglas	Evaluacion de condiciones configurables para decidir resultado
Notificaciones	Envio multi-canal (SMS, email, webhook, push) por eventos del flujo
Asignacion	Vincular flujos publicados a tenants u organizaciones

Actores

Actor	Interaccion con ImagFlow
Platform Admin	Crea, edita y publica flujos. Configura proveedores y templates.
Delegated Admin	Asigna flujos a tenants. Duplica templates.
Tenant Admin	Ve flujos asignados. No puede editarlos.
Operator	Crea solicitudes (requests) que inician la ejecucion de un flujo.
Usuario Final	Ejecuta los pasos del flujo via link publico (sin autenticacion).
ImagLend	Invoca flujos de validacion como parte del proceso de credito.
ImagSign	Es invocado como proveedor de firma dentro de un paso del flujo.

Arquitectura Interna

Sub-componentes

Flow Service

Gestiona el ciclo de vida de flujos:

• CRUD de flujos y versiones
• Configuracion de pasos (tipo, proveedor, config UI, reintentos)
• Configuracion de reglas (condiciones, acciones)
• Configuracion de notificaciones (triggers, canales, templates)
• Versionamiento inmutable (draft/published/archived)
• Templates y duplicacion

Request Service

Gestiona solicitudes (instancias de ejecucion de un flujo):

• Crear solicitud (genera access_token, link publico)
• Ciclo de vida: created, in_progress, capture_completed, processing, completed, failed, expired
• Almacena intentos (attempts) por paso
• Almacena resultados de enriquecimiento (enrichments)
• Almacena decision final

Execution Engine

Orquesta la ejecucion cuando el usuario final accede al link:

• Valida token y estado de la solicitud
• Gestiona sesion de ejecucion en Valkey (paso actual, intentos, estado)
• Invoca Provider Gateway para cada paso
• Controla reintentos y cooldowns
• Dispara procesos asincronos al completar captura
• Publica eventos de progreso

Provider Gateway

Abstraccion unificada para proveedores externos:

• Adapter pattern (una interfaz por tipo de servicio)
• Failover configurable (proveedor primario y secundario)
• Circuit breaker (Polly)
• Metricas por proveedor (latencia, errores, failovers)
• Registro de nuevos proveedores sin cambiar codigo core

Rules Engine

Evalua condiciones configurables sobre los datos recopilados:

• Condiciones simples (campo, operador, valor)
• Condiciones compuestas (AND, OR, anidadas)
• Datos historicos del sujeto (via ImagID)
• Acciones: aprobar, rechazar, escalar, notificar, marcar

Notification Service

Envia notificaciones multi-canal:

• Triggers: on_complete, on_reject, on_approve, on_expire, on_step_fail
• Canales: SMS, email, webhook, push
• Templates configurables por flujo
• Webhooks firmados con HMAC para clientes

Modelo de Versionamiento

Estado	Editable	Asignable	Usable en solicitudes
Draft	Si	No	No
Published	No (inmutable)	Si	Si
Archived	No	No	Solo solicitudes existentes
Discarded	No	No	No

Reglas:

• Solo 1 draft activo por flujo
• Solo 1 version published por flujo
• Al publicar, la version published actual pasa a archived
• Las solicitudes referencian flow_version_id, no flow_id
• Si se publica v2, las solicitudes creadas con v1 siguen con v1

Tipos de Paso

Tipo	Descripcion	Proveedor
form	Formulario configurable (campos, validaciones)	Ninguno (captura local)
liveness	Verificacion facial en vivo	Biometria
card_capture	Captura de documento (frente/reverso)	OCR
signature	Firma digital o electronica	ImagSign
validation	Validacion contra registros oficiales	Registros, demograficos
custom	Paso generico extensible	Configurable

Ciclo de Vida de una Solicitud

Integracion con Otros Dominios

ImagFlow como proveedor de servicios

Consumidor	Como usa ImagFlow	Endpoint
ImagLend	Invoca flujo de validacion de identidad	POST /api/v1/executions/trigger
ImagLend	Consulta resultado de ejecucion	GET /api/v1/executions/{id}/result

ImagFlow como consumidor

Proveedor	Que consume ImagFlow	Endpoint
ImagSign	Ejecuta firma como paso del flujo	POST /api/v1/signatures/request
ImagID	Consulta historial del sujeto para reglas	GET /api/v1/subjects/{id}/metrics

Eventos publicados

Evento	Routing Key	Consumidores
Flujo completado	flow.execution.completed	ImagLend, ImagID
Flujo fallido	flow.execution.failed	ImagID
Paso completado	flow.step.completed	ImagID
Version publicada	flow.version.published	Audit

Eventos consumidos

Evento	Routing Key	Accion
Firma completada	sign.signature.completed	Marcar paso de firma como completado
Firma rechazada	sign.signature.rejected	Marcar paso de firma como fallido
Sujeto blacklisted	subject.profile.blacklisted	Registrar en cache para reglas

Repositorio

• Repo: imagy-flow-engine
• Base de datos: imagy_flow
• Puerto local: 4001
• Equipo: Team Flow

Documentos Relacionados

• Modelo de Datos — Tablas, relaciones, schemas
• API Reference — Endpoints publicos e internos
• Provider Gateway — Adapters, failover, circuit breaker
• Eventos — Eventos producidos y consumidos