Visão Geral do Motor Kikwiflow

O Kikwiflow é um motor de orquestração de processos (workflow/BPM) construído do zero em Java 21, pensado para times de engenharia que precisam de automação de processos de negócio sem abrir mão de tudo que torna um código-base Java produtivo: tipagem forte, refatoração segura em IDE, testes unitários triviais e depuração com breakpoint. Esta seção da documentação (docs/engine) descreve o funcionamento interno do motor — os componentes do módulo kikwi-core e como eles colaboram para levar uma instância de processo do início ao fim.

Por que Kikwiflow existe

Motores de BPM tradicionais (Camunda, Activiti, jBPM e similares) modelam processos em BPMN XML e resolvem decisões e scripts com linguagens de expressão embutidas (SpEL, JUEL, FEEL). Isso funciona, mas impõe um custo real de developer experience: XML não tem autocomplete confiável, expressões embutidas em string não são refatoráveis pela IDE, e depurar uma expressão FEEL que falhou em produção normalmente significa lidar com stack traces que apontam para o motor, não para o seu código.

O Kikwiflow parte de uma escolha de design deliberada e diferente:

:::tip Filosofia central Um processo é um grafo de nós descrito em JSON. A lógica de cada nó é uma classe Java comum, registrada como bean Spring. Não há expression language, não há scripting embutido, não há XML. :::

Na prática, isso significa que:

• Uma tarefa executável (EXECUTABLE_TASK) não aponta para uma expressão — aponta para o nome de um bean Spring que implementa a interface TaskHandler. Você escreve handle(ExecutionContext execution) como escreveria qualquer outro componente Spring, com acesso total a injeção de dependência, testes com Mockito e breakpoints do seu jeito habitual.
• Uma decisão em um gateway exclusivo não é uma expressão booleana em uma string — é o retorno de um método resolve(EvaluationContext context) de uma classe que implementa AnswerProvider, tão testável quanto qualquer outra classe de domínio.
• Cálculo de prazos dinâmicos de timer (DueDateProvider) e políticas de retry seguem o mesmo padrão: interface Java pequena, implementação livre, resolução por nome de bean em tempo de execução.

Essa escolha tem um preço — ela acopla a definição do processo ao classpath da aplicação que o executa — mas o retorno é um modelo de execução onde toda a lógica de negócio vive onde o resto do seu código já vive, sob controle de versão, revisão de código e cobertura de testes normais.

Camadas do motor

O Kikwiflow é dividido em módulos com fronteiras de responsabilidade explícitas (ver pom.xml raiz para a ordem de build). Os grupos relevantes para entender a execução são:

Camada	Módulos	Responsabilidade
Modelo	kikwi-model	Records imutáveis: definição de processo (ProcessDefinition, FlowNodeDefinition e suas variantes), estado de execução (ProcessInstance, ExecutableTask, ExternalTask, Incident), enums de domínio.
Contratos (SPI)	kikwi-execution-api, kikwi-runtime-persistence-api, kikwi-security-api, kikwi-lightweight-events-api	Interfaces que o motor consome e que aplicações/plugins implementam: TaskHandler, AnswerProvider, DueDateProvider, RetryPolicyEvaluator, KikwiEngineRepository, DeploymentSecurityManager, ExecutionEventListener.
Motor de execução	kikwi-core	A implementação de fato: KikwiflowEngine (fachada), Navigator (roteamento), ProcessExecutionManager (loop de execução em memória), ContinuationService (fronteiras transacionais), TaskAcquirer/TaskExecutor (polling e despacho), FailureHandler (retry/incidentes).
Parsing	kikwi-parser-jackson	Deserialização polimórfica do JSON .kikwi para o modelo de domínio, com dispatch por campo "type".
Persistência	kikwi-runtime-persistence-mongodb	Única implementação de produção de KikwiEngineRepository hoje — MongoDB nativo, com commitWork() transacional via ClientSession.withTransaction.
Integração Spring	kikwi-spring-boot-autoconfigure e módulos -starter	Fiação automática: resolve TaskHandler/AnswerProvider/DueDateProvider como beans Spring nomeados, expõe KikwiflowProperties, autodeploy de definições JSON do classpath.
API de gestão	kikwi-management-rest*	REST para consulta e operação: busca de instâncias, claim/complete de tarefas externas, retry de incidentes, SSE de estatísticas.

Cada uma dessas camadas é descrita em detalhe nas páginas seguintes desta seção.

CQRS como princípio arquitetural

O motor separa explicitamente comando (mutação de estado) de consulta (leitura):

• Lado de comando: KikwiflowEngine → KikwiEngineRepository (interface que estende CommandRepository e QueryRepository). Toda mutação de estado — criar/atualizar/deletar uma ProcessInstance, criar/apagar tarefas, registrar incidentes — passa por um único método transacional: commitWork(UnitOfWork).
• Lado de consulta: QueryRepository expõe builders fluentes (createProcessInstanceQuery(), createExternalTaskQuery()), consumidos por kikwi-runtime-query-api/ExternalTaskQueryService e pela API REST de gestão. Consultas nunca passam pelo UnitOfWork.

Essa separação existe porque as duas cargas de trabalho têm perfis de acesso completamente diferentes: o lado de comando precisa de forte consistência transacional (mover uma instância de um nó para o próximo não pode deixar tarefas órfãs), enquanto o lado de consulta precisa de flexibilidade de filtros e paginação sem acoplar o schema interno de execução à experiência de busca do usuário final.

O que vem a seguir

As próximas páginas cobrem, em ordem, os mecanismos concretos do motor:

1. Modelo de Processo e Nós de Fluxo — anatomia de um .kikwi e a hierarquia de tipos de nó.
2. Navegação e Gateways de Decisão — como o Navigator resolve o próximo passo.
3. Timers e Agendamento — timers de borda e tarefas recorrentes.
4. Retry e Resiliência — políticas de nova tentativa e incidentes.
5. Execução Síncrona e Assíncrona — o modelo de fronteiras transacionais.
6. Workers e Tarefas Externas — o poller TaskAcquirer e o ciclo de vida de ExternalTask.
7. Tratamento de Erros de Negócio — ProcessErrorException e handlers de borda.
8. Eventos e Observabilidade — eventos leves vs. padrão outbox.
9. Persistência e Consistência Transacional — UnitOfWork e o contrato KikwiEngineRepository.
10. Segurança e Multi-tenancy — SPIs de segurança e isolamento por tenant.
11. Referência de Configuração — todas as propriedades kikwiflow.*, incluindo kikwiflow.monitor-ui.*.

As páginas seguintes aprofundam validação de processo e módulos complementares:

12. Regras de Processo Válido — o que o DeployValidator de fato rejeita.
13. Métricas OpenTelemetry.
14. kikwi-monitor: Lib Spring que Embarca o Monitor — como servir a UI de monitoramento no próprio processo da aplicação.

A cobertura nó-a-nó dos tipos de correlação (EVENT_CATCHER, EVENT_THROWER, BOUNDARY_INTERRUPTIVE_CATCH_EVENT), do TIMER_TASK e dos subprocessos (CALL_ACTIVITY_COORDINATOR) está no Guia do Desenvolvedor — as páginas de especificação interna desses nós entram em uma leva posterior da documentação de motor.