Skip to main content
Este guia aborda como projetar workflows no Flowker — desde entender os tipos de nos e arestas ate aplicar padroes comuns para fluxos fintech do mundo real. Tambem cobre as transicoes de status, os limites tecnicos e as melhores praticas para ajuda-lo a construir orquestracoes confiaveis e manteniveis.

​
Tipos de nos

Cada workflow e construido a partir de nos. Cada no tem um type que determina como o Flowker o processa em tempo de execucao.

​
trigger

O ponto de entrada de um workflow. Todo workflow deve comecar com um no trigger. Quando a execucao de um workflow e iniciada, o motor entra por este no e comeca o roteamento a partir dele. 
{
  "id": "node-trigger",
  "type": "trigger",
  "name": "Payment Received"
}

​
executor

Chama um executor externo — um servico HTTP, API ou provedor registrado no Flowker. Este e o bloco de construcao principal para integracoes com motores de fraude, provedores de pagamento, servicos de notificacao e outros sistemas externos. 
{
  "id": "node-fraud-check",
  "type": "executor",
  "name": "Check Fraud Score"
}

​
conditional

Avalia uma expressao contra o contexto de execucao e roteia para diferentes ramificacoes com base no resultado. Os nos condicionais permitem logica de ramificacao — por exemplo, rotear para um caminho de aprovacao quando a pontuacao de risco e alta, ou continuar diretamente quando e baixa. 
{
  "id": "node-risk-decision",
  "type": "conditional",
  "name": "Evaluate Risk Score"
}

​
action

Um no de acao generico para etapas que nao envolvem chamadas externas mas representam operacoes significativas dentro do workflow — como transformar dados, emitir um evento ou registrar uma mudanca de estado. 
{
  "id": "node-record-approval",
  "type": "action",
  "name": "Record Approval Decision"
}

​
Arestas

As arestas conectam nos e definem o caminho de execucao. Cada aresta possui os seguintes campos:
CampoDescricao
idIdentificador unico da aresta
sourceID do no de origem
targetID do no de destino
sourceHandleQual handle (porta de saida) do no de origem origina esta aresta
conditionUma expressao que deve ser avaliada como true para que esta aresta seja seguida
labelRotulo legivel para a aresta (usado em visualizacao e depuracao)

​
Exemplo de aresta

{
  "id": "edge-approved",
  "source": "node-risk-decision",
  "target": "node-process-payment",
  "sourceHandle": "approved",
  "condition": "data.riskScore < 70",
  "label": "Approved"
}
O campo condition aceita expressoes avaliadas contra o contexto de execucao. Quando omitido, a aresta e sempre seguida se o no de origem completar com sucesso.

​
Transicoes de status

Os workflows se movem por um ciclo de vida bem definido. Entender as transicoes de status e fundamental para implantar e iterar workflows de forma segura. Diagrama de transicao de status de workflow mostrando tres estados: draft, active e inactive. Uma seta rotulada 'activate' aponta de draft para active. Uma seta rotulada 'deactivate' aponta de active para inactive. Nao ha transicoes de volta para draft nem de inactive para qualquer outro estado.
  • draft — O estado inicial. Todas as modificacoes (adicionar nos, editar arestas, alterar configuracao) so sao permitidas no status draft.
  • active — Um workflow que foi ativado. Pode ser executado. Nenhuma modificacao e permitida enquanto estiver ativo.
  • inactive — Um workflow que foi desativado. Nao pode mais ser executado.

​
Regras

  • Somente um workflow em draft pode ser ativado (transicao: draft → active).
  • Somente um workflow active pode ser desativado (transicao: active → inactive).
  • Tentar uma transicao invalida retorna o erro FLK-0102.
  • Tentar modificar um workflow que nao esta em draft retorna o erro FLK-0103.

​
Iterando com seguranca usando clone

Para modificar um workflow ativo, clone-o primeiro. A clonagem cria um novo draft a partir de qualquer status, copiando todos os nos e arestas. Voce pode entao editar o rascunho, testa-lo e ativa-lo quando estiver pronto — sem afetar a versao que esta sendo executada no momento. Esta e a abordagem recomendada para versionar workflows em producao.

​
Limites tecnicos

LimiteValorCodigo de erro
Maximo de nos por workflow100FLK-0113
Maximo de arestas por workflow200FLK-0114
Maximo do payload de entrada de execucao1 MBFLK-0506
Mantenha esses limites em mente ao projetar fluxos complexos. Workflows com mais de ~50 nos tipicamente sao um sinal de que o fluxo deve ser dividido em workflows menores e composiveis.

​
Padroes comuns

​
Sequencial

O padrao mais simples. Os nos executam um apos o outro em uma cadeia linear. Use quando cada etapa depende do resultado da anterior e nao ha ramificacao. Padrao de workflow sequencial: um no trigger se conecta a um primeiro no executor, que se conecta a um segundo no executor, que se conecta a um terceiro no executor. Todas as conexoes sao setas unidirecionais formando uma linha reta. Exemplo: Orquestracao de pagamentos 
{
  "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)

Multiplos nos executor sao iniciados a partir de um ponto de entrada comum e seus resultados sao coletados em um no de juncao. Use quando verificacoes ou chamadas independentes podem ocorrer concorrentemente para reduzir o tempo total de execucao. Padrao de workflow paralelo (fan-out / fan-in): um no trigger se divide em dois nos executor executando concorrentemente. Ambos os nos executor convergem em um unico no de acao de juncao. Este padrao e util quando voce precisa chamar multiplos provedores de fraude ou conformidade simultaneamente e agregar suas respostas antes de tomar uma decisao de roteamento.

​
Ramificacao condicional

Um no conditional avalia uma expressao e roteia a execucao para diferentes nos dependendo do resultado. Cada aresta de saida do no condicional carrega uma expressao condition. Padrao de workflow com ramificacao condicional: um no trigger se conecta a um no executor, que se conecta a um no condicional. O no condicional tem duas setas de saida: uma rotulada 'Path A' apontando para um primeiro no executor, e uma rotulada 'Path B' apontando para um segundo no executor. Exemplo: Verificacao 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"
    }
  ]
}

​
Exemplos do mundo real

​
Verificacao antifraude

Uma transacao chega, uma pontuacao de fraude e obtida de um motor externo, e o resultado roteia a execucao para um caminho de aprovacao ou rejeicao. 
{
  "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"
    }
  ]
}

​
Orquestracao de pagamentos

Um fluxo linear que valida os dados do pagamento recebido, roteia para o provedor apropriado e envia uma confirmacao. 
{
  "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

Os documentos de um cliente sao verificados por um servico externo. Um no condicional avalia se e necessaria revisao manual. Se sim, uma acao de aprovacao manual e acionada antes de ativar a conta. 
{
  "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" }
  ]
}

​
Fluxo de aprovacao manual

Uma solicitacao e enviada para revisao. Uma acao de aprovacao aguarda uma decisao. Um no condicional entao roteia para o caminho de aprovacao ou rejeicao. 
{
  "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"
    }
  ]
}

​
Melhores praticas

​
Convencoes de nomeacao de nos

Use nomes descritivos orientados a acao que comuniquem o que o no faz — nao de que tipo e.
  • Correto: Validate Payment Data, Get Fraud Score, Notify Customer, Await Approval
  • Incorreto: executor1, conditional node, node3
Bons nomes tornam os workflows legiveis sem abrir a configuracao do no. Eles tambem aparecem nos logs de auditoria e traces de execucao, tornando a depuracao significativamente mais rapida.

​
Expressoes de condicao em arestas

As condicoes nas arestas sao avaliadas contra o contexto de execucao. Mantenha-as simples e explicitas:
  • Use comparacoes diretas de campos: data.status == 'approved'
  • Use comparacoes numericas: data.riskScore < 70
  • Use campos booleanos: data.reviewRequired == true
Evite expressoes complexas que sejam dificeis de ler ou depurar. Se a logica nao for trivial, considere rotear atraves de um no conditional que encapsule a decisao com um nome claro. Uma expressao invalida retorna FLK-0105. Sempre valide as expressoes antes de ativar um workflow.

​
Estrategias de tratamento de erros

Projete workflows para tratar falhas de forma explicita:
  • Adicione caminhos de rejeicao a partir de nos conditional para cada ponto de decisao que possa falhar.
  • Use nos executor separados para logica de retentativa ou provedores de fallback.
  • Nomeie os caminhos de erro de forma clara (por exemplo, Reject and Notify, Fallback to Manual Review) para que os logs de auditoria sejam autoexplicativos.

​
Evitando ciclos

O Flowker usa um protetor de ciclos baseado em DFS em tempo de execucao. Se um ciclo for detectado durante a execucao, o workflow falha com FLK-0508. Os ciclos nao sao detectados em tempo de design, portanto valide a estrutura das suas arestas antes de ativar. Regras para prevenir ciclos:
  • As arestas devem sempre apontar para frente no fluxo — nunca de volta para um no executado anteriormente.
  • Revise o grafo visualmente antes de ativar qualquer workflow com ramificacoes ou caminhos que se fundem.
  • Se uma retentativa ou loop for necessario, modele como uma invocacao de workflow separada, nao como uma aresta de retorno no grafo atual.

​
Versionamento via clone

Nunca edite um workflow ativo diretamente. Em vez disso:
  1. Clone o workflow (cria um novo draft com todos os nos e arestas copiados).
  2. Faca suas alteracoes no rascunho.
  3. Teste o rascunho com execucoes de teste.
  4. Ative a nova versao.
  5. Desative a versao anterior se nao for mais necessaria.
Isso preserva o historico de execucao da versao ativa e oferece um caminho limpo de rollback se a nova versao apresentar problemas.

​
Referencia de erros

Os seguintes codigos de erro sao relevantes para o design e a execucao de workflows:
CodigoDescricao
FLK-0102Invalid status transition
FLK-0103Workflow cannot be modified — not in draft status
FLK-0105Invalid conditional expression
FLK-0113Too many nodes — maximum is 100
FLK-0114Too many edges — maximum is 200
FLK-0506Execution input payload too large — maximum is 1 MB
FLK-0508Cycle detected during workflow execution