Guia de diseno de workflows

Esta guia cubre como disenar workflows en Flowker — desde entender los tipos de nodos y aristas hasta aplicar patrones comunes para flujos fintech del mundo real. Tambien cubre las transiciones de estado, los limites tecnicos y las mejores practicas para ayudarte a construir orquestaciones confiables y mantenibles.

Tipos de nodos

Cada workflow esta construido a partir de nodos. Cada nodo tiene un type que determina como Flowker lo procesa en tiempo de ejecucion.

trigger

El punto de entrada de un workflow. Cada workflow debe comenzar con un nodo trigger. Cuando se inicia la ejecucion de un workflow, el motor entra por este nodo y comienza el enrutamiento desde el.

{
  "id": "node-trigger",
  "type": "trigger",
  "name": "Payment Received"
}

executor

Llama a un executor externo — un servicio HTTP, API o proveedor registrado en Flowker. Este es el bloque de construccion principal para integrarse con motores de fraude, proveedores de pagos, servicios de notificacion y otros sistemas externos.

{
  "id": "node-fraud-check",
  "type": "executor",
  "name": "Check Fraud Score"
}

conditional

Evalua una expresion contra el contexto de ejecucion y enruta a diferentes ramas segun el resultado. Los nodos condicionales permiten la logica de bifurcacion — por ejemplo, enrutar a un camino de aprobacion cuando la puntuacion de riesgo es alta, o continuar directamente cuando es baja.

{
  "id": "node-risk-decision",
  "type": "conditional",
  "name": "Evaluate Risk Score"
}

action

Un nodo de accion generico para pasos que no involucran llamadas externas pero representan operaciones significativas dentro del workflow — como transformar datos, emitir un evento o registrar un cambio de estado.

{
  "id": "node-record-approval",
  "type": "action",
  "name": "Record Approval Decision"
}

Aristas

Las aristas conectan nodos y definen el camino de ejecucion. Cada arista tiene los siguientes campos:

Campo	Descripcion
`id`	Identificador unico de la arista
`source`	ID del nodo de origen
`target`	ID del nodo de destino
`sourceHandle`	Que handle (puerto de salida) del nodo de origen origina esta arista
`condition`	Una expresion que debe evaluarse como `true` para que se siga esta arista
`label`	Etiqueta legible para la arista (utilizada en visualizacion y depuracion)

Ejemplo de arista

{
  "id": "edge-approved",
  "source": "node-risk-decision",
  "target": "node-process-payment",
  "sourceHandle": "approved",
  "condition": "data.riskScore < 70",
  "label": "Approved"
}

El campo condition acepta expresiones evaluadas contra el contexto de ejecucion. Cuando se omite, la arista siempre se sigue si el nodo de origen completa exitosamente.

Transiciones de estado

Los workflows se mueven a traves de un ciclo de vida bien definido. Entender las transiciones de estado es critico para desplegar e iterar workflows de forma segura. Diagrama de transicion de estado de workflow que muestra tres estados: draft, active e inactive. Una flecha etiquetada 'activate' apunta de draft a active. Una flecha etiquetada 'deactivate' apunta de active a inactive. No hay transiciones de vuelta a draft ni de inactive a ningun otro estado.

Diagrama de transicion de estado de workflow que muestra tres estados: draft, active e inactive. Una flecha etiquetada 'activate' apunta de draft a active. Una flecha etiquetada 'deactivate' apunta de active a inactive. No hay transiciones de vuelta a draft ni de inactive a ningun otro estado.

draft — El estado inicial. Todas las modificaciones (agregar nodos, editar aristas, cambiar configuracion) solo estan permitidas en estado draft.
active — Un workflow que ha sido activado. Puede ser ejecutado. No se permiten modificaciones mientras esta activo.
inactive — Un workflow que ha sido desactivado. Ya no puede ser ejecutado.

Reglas

Solo un workflow en draft puede ser activado (transicion: draft → active).
Solo un workflow active puede ser desactivado (transicion: active → inactive).
Intentar una transicion invalida devuelve el error FLK-0102.
Intentar modificar un workflow que no esta en draft devuelve el error FLK-0103.

Iterar de forma segura con clone

Para modificar un workflow activo, primero clonalo. La clonacion crea un nuevo draft desde cualquier estado, copiando todos los nodos y aristas. Luego puedes editar el borrador, probarlo y activarlo cuando este listo — sin afectar la version que esta ejecutandose actualmente. Este es el enfoque recomendado para versionar workflows en produccion.

Limites tecnicos

Limite	Valor	Codigo de error
Maximo de nodos por workflow	100	`FLK-0113`
Maximo de aristas por workflow	200	`FLK-0114`
Maximo del payload de entrada de ejecucion	1 MB	`FLK-0506`

Ten en cuenta estos limites al disenar flujos complejos. Los workflows con mas de ~50 nodos tipicamente son una senal de que el flujo deberia dividirse en workflows mas pequenos y componibles.

Patrones comunes

Secuencial

El patron mas simple. Los nodos se ejecutan uno tras otro en una cadena lineal. Usa esto cuando cada paso depende del resultado del anterior y no hay bifurcacion. Patron de workflow secuencial: un nodo trigger se conecta a un primer nodo executor, que se conecta a un segundo nodo executor, que se conecta a un tercer nodo executor. Todas las conexiones son flechas unidireccionales formando una linea recta.

Ejemplo: Orquestacion de pagos

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation Notification" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Routed" }
  ]
}

Paralelo (fan-out / fan-in)

Multiples nodos executor se inician desde un punto de entrada comun y sus resultados se recopilan en un nodo de union. Usa esto cuando comprobaciones o llamadas independientes pueden ocurrir concurrentemente para reducir el tiempo total de ejecucion. Patron de workflow paralelo (fan-out / fan-in): un nodo trigger se divide en dos nodos executor ejecutandose concurrentemente. Ambos nodos executor luego convergen en un unico nodo de accion de union.

Este patron es util cuando necesitas llamar a multiples proveedores de fraude o cumplimiento simultaneamente y agregar sus respuestas antes de tomar una decision de enrutamiento.

Bifurcacion condicional

Un nodo conditional evalua una expresion y enruta la ejecucion a diferentes nodos dependiendo del resultado. Cada arista saliente del nodo condicional lleva una expresion condition. Patron de workflow con bifurcacion condicional: un nodo trigger se conecta a un nodo executor, que se conecta a un nodo condicional. El nodo condicional tiene dos flechas salientes: una etiquetada 'Path A' apuntando a un primer nodo executor, y una etiquetada 'Path B' apuntando a un segundo nodo executor.

Ejemplo: Verificacion antifraude

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    { "id": "n3", "type": "conditional", "name": "Evaluate Score" },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject Transaction" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "approved",
      "condition": "data.fraudScore < 70",
      "label": "Approved"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "rejected",
      "condition": "data.fraudScore >= 70",
      "label": "Rejected"
    }
  ]
}

Ejemplos del mundo real

Verificacion antifraude

Una transaccion llega, se obtiene una puntuacion de fraude de un motor externo, y el resultado enruta la ejecucion a un camino de aprobacion o rechazo.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    { "id": "n3", "type": "conditional", "name": "Evaluate Fraud Score" },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject and Notify" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "approved",
      "condition": "data.fraudScore < 70",
      "label": "Low risk"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "rejected",
      "condition": "data.fraudScore >= 70",
      "label": "High risk"
    }
  ]
}

Orquestacion de pagos

Un flujo lineal que valida los datos del pago entrante, los enruta al proveedor apropiado y envia una confirmacion.

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Payment Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Payment routed" }
  ]
}

Onboarding KYC

Los documentos de un cliente son verificados por un servicio externo. Un nodo condicional evalua si se requiere revision manual. De ser asi, se activa una accion de aprobacion manual antes de activar la cuenta.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Onboarding Started" },
    { "id": "n2", "type": "executor",    "name": "Run Document Check" },
    { "id": "n3", "type": "conditional", "name": "Manual Review Required?" },
    { "id": "n4", "type": "action",      "name": "Request Manual Approval" },
    { "id": "n5", "type": "executor",    "name": "Activate Account" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Check complete" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "review",
      "condition": "data.reviewRequired == true",
      "label": "Needs review"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "clear",
      "condition": "data.reviewRequired == false",
      "label": "Auto-approved"
    },
    { "id": "e5", "source": "n4", "target": "n5", "label": "Approved" }
  ]
}

Flujo de aprobacion manual

Se envia una solicitud para revision. Una accion de aprobacion espera una decision. Un nodo condicional luego enruta al camino de aprobacion o rechazo.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Request Submitted" },
    { "id": "n2", "type": "executor",    "name": "Submit for Review" },
    { "id": "n3", "type": "action",      "name": "Await Approval Decision" },
    { "id": "n4", "type": "conditional", "name": "Decision Received" },
    { "id": "n5", "type": "executor",    "name": "Process Approved Request" },
    { "id": "n6", "type": "executor",    "name": "Notify Rejection" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Submitted" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Decision received" },
    {
      "id": "e4",
      "source": "n4",
      "target": "n5",
      "sourceHandle": "approved",
      "condition": "data.decision == 'approved'",
      "label": "Approved"
    },
    {
      "id": "e5",
      "source": "n4",
      "target": "n6",
      "sourceHandle": "rejected",
      "condition": "data.decision == 'rejected'",
      "label": "Rejected"
    }
  ]
}

Mejores practicas

Convenciones de nombres de nodos

Usa nombres descriptivos orientados a la accion que comuniquen lo que hace el nodo — no de que tipo es.

Correcto: Validate Payment Data, Get Fraud Score, Notify Customer, Await Approval
Incorrecto: executor1, conditional node, node3

Los buenos nombres hacen que los workflows sean legibles sin abrir la configuracion del nodo. Tambien aparecen en los logs de auditoria y trazas de ejecucion, haciendo la depuracion significativamente mas rapida.

Expresiones de condicion en aristas

Las condiciones en las aristas se evaluan contra el contexto de ejecucion. Mantenlas simples y explicitas:

Usa comparaciones directas de campos: data.status == 'approved'
Usa comparaciones numericas: data.riskScore < 70
Usa campos booleanos: data.reviewRequired == true

Evita expresiones complejas que sean dificiles de leer o depurar. Si la logica no es trivial, considera enrutar a traves de un nodo conditional que encapsule la decision con un nombre claro. Una expresion invalida devuelve FLK-0105. Siempre valida las expresiones antes de activar un workflow.

Estrategias de manejo de errores

Disena workflows para manejar fallos de forma explicita:

Agrega caminos de rechazo desde nodos conditional para cada punto de decision que pueda fallar.
Usa nodos executor separados para logica de reintentos o proveedores de respaldo.
Nombra los caminos de error de forma clara (por ejemplo, Reject and Notify, Fallback to Manual Review) para que los logs de auditoria sean autoexplicativos.

Evitando ciclos

Flowker usa un protector de ciclos basado en DFS en tiempo de ejecucion. Si se detecta un ciclo durante la ejecucion, el workflow falla con FLK-0508. Los ciclos no se detectan en tiempo de diseno, asi que valida la estructura de tus aristas antes de activar. Reglas para prevenir ciclos:

Las aristas siempre deben apuntar hacia adelante en el flujo — nunca hacia un nodo ejecutado previamente.
Revisa el grafo visualmente antes de activar cualquier workflow con bifurcaciones o caminos que se fusionan.
Si se necesita un reintento o bucle, modelalo como una invocacion de workflow separada, no como una arista de retorno en el grafo actual.

Versionado mediante clone

Nunca edites un workflow activo directamente. En su lugar:

Clona el workflow (crea un nuevo draft con todos los nodos y aristas copiados).
Realiza tus cambios en el borrador.
Prueba el borrador con ejecuciones de prueba.
Activa la nueva version.
Desactiva la version anterior si ya no es necesaria.

Esto preserva el historial de ejecucion de la version activa y te da un camino limpio de rollback si la nueva version tiene problemas.

Referencia de errores

Los siguientes codigos de error son relevantes para el diseno y la ejecucion de workflows:

Codigo	Descripcion
`FLK-0102`	Invalid status transition
`FLK-0103`	Workflow cannot be modified — not in draft status
`FLK-0105`	Invalid conditional expression
`FLK-0113`	Too many nodes — maximum is 100
`FLK-0114`	Too many edges — maximum is 200
`FLK-0506`	Execution input payload too large — maximum is 1 MB
`FLK-0508`	Cycle detected during workflow execution

​Tipos de nodos

​trigger

​executor

​conditional

​action

​Aristas

​Ejemplo de arista

​Transiciones de estado

​Reglas

​Iterar de forma segura con clone

​Limites tecnicos

​Patrones comunes

​Secuencial

​Paralelo (fan-out / fan-in)

​Bifurcacion condicional

​Ejemplos del mundo real

​Verificacion antifraude

​Orquestacion de pagos

​Onboarding KYC

​Flujo de aprobacion manual

​Mejores practicas

​Convenciones de nombres de nodos

​Expresiones de condicion en aristas

​Estrategias de manejo de errores

​Evitando ciclos

​Versionado mediante clone

​Referencia de errores