AkôFlow - Migração para Vite + React

[zaclummys]

Contexto

Atualmente, o AkôFlow Admin utiliza arquivos HTML com interpolação de strings para servir as páginas do painel administrativo. Apesar de atender às necessidades do usuário em termos de configuração e execução dos workflows, essa abordagem carece de boas práticas modernas de desenvolvimento front-end:

• Não é possível testar unitariamente os componentes;
• Não há framework para renderização e reutilização de elementos de UI;
• O AkôFlow Engine absorve responsabilidades relacionadas à interface, aumentando seu escopo indevidamente.

Proposta

Gostaria de propor a utilização do Vite + React para a geração estática do AkôFlow Admin, em um módulo separado do AkôFlow Engine. Com isso, se tornará possível:

• Reutilizar componentes de forma estruturada;
• Padronizar a interface e a experiência de usuário do AkôFlow;
• Melhorar e controlar a qualidade através de:
  • Testes unitários;
  • Testes de fim a fim com navegadores reais;
  • Checks automáticos de qualidade em PRs (ex.: test, lint, build);
• Comprimir e otimizar o bundle final automaticamente.
• Reduzir e isolar as responsabilidades do engine, mantendo a UI exclusivamente no AkôFlow Admin.

Para melhorar a organização do repositório, proponho também a adoção do padrão monorepo, no qual diferentes módulos coexistem no mesmo repositório. Ferramentas como Turborepo, NPM Workspaces e Lerna podem auxiliar, embora a mudança mais importante seja estrutural:

.
└── modules/
    ├── akoflow-engine
    └── akoflow-admin

Nesse formato:

• akoflow-engine mantém o projeto Go e as funcionalidades centrais;
• akoflow-admin mantém o projeto Vite + React e toda a lógica da interface administrativa.

O akoflow-engine continuaria servindo o AkôFlow Admin, mas agora servindo arquivos estáticos, sem qualquer interpolação dinâmica.

Fluxo

1. O akoflow-admin executa npm run build, produzindo uma pasta estática (ex.: dist/).
2. O akoflow-engine, ao ser compilado, incorpora ou referencia essa pasta.
3. Qualquer requisição para /akoflow-admin/* retorna arquivos dessa pasta, sem manipulação ou templates Go.

Esse modelo é simples, eficiente e reduz responsabilidades do engine.

Migração

Como já existe um AkôFlow Admin em produção, a migração pode (e deve) ser feita de forma gradual. Existem duas abordagens possíveis:

1. Branch dedicada (ex.: feature-vite-akoflow-admin):

   • Evita exposição prematura de uma interface incompleta.
   • Facilita reverts caso a proposta não avance.

2. Duas versões lado a lado, controladas por feature flag (minha preferência):

   • Evita conflitos de código entre versões;
   • Permite testar ambas as implementações durante o desenvolvimento;
   • Possibilita alternar entre uma versão e outra rapidamente;
   • Reduz riscos durante a transição.

Versionamento

Com a adoção de um monorepo, o versionamento seria unificado: uma única versão para todo o repositório, em vez de versões independentes por módulo.

Acesso à API

Atualmente, o AkôFlow Admin consome a API via http://localhost:8080. Esse comportamento pode ser mantido ou parametrizado através de uma variável de ambiente (process.env.BASE_API_URL).

O Vite substitui essas variáveis em tempo de build, garantindo URLs corretas no bundle final.

CI

A migração introduz novas necessidades de pipeline, incluindo:

• Instalação das dependências do akoflow-admin (npm install);
• Execução dos checks de qualidade (lint, test, etc.);
• Execução do build estático (npm run build);
• Inclusão da pasta resultante no processo de build e distribuição do akoflow-engine.

Será necessário criar novos checks de qualidade específicos para o front-end e ajustar o script de compilação atual para incorporar o build estático gerado pelo Vite.

[zaclummys]

FYI @ovvesley

[ovvesley]

Obrigado pela issue, @zaclummys - ela faz total sentido 👍

Essa separação começou dessa forma porque, no início do AkôFlow, a ideia era manter tudo em um único projeto para reduzir complexidade inicial. Porém, com o crescimento do projeto e das responsabilidades do sistema, fica cada vez mais claro que a separação entre engine e interface é o caminho correto.

Concordo totalmente com os pontos levantados: isolamento de responsabilidades, melhor qualidade de UI, testes, reutilização de componentes e redução do escopo do engine.

Dito isso, tomamos uma decisão de arquitetura muito próxima da sua proposta, com uma pequena diferença conceitual:
• O AkôFlow Admin será um projeto separado, focado exclusivamente em interface;
• Ele funcionará como um SPA em React, consumindo o AkôFlow via API HTTP;
• O AkôFlow Engine não terá mais qualquer lógica de UI, apenas exposição de API e execução de workflows.

Já criei o repositório para o AkôFlow Admin, e a ideia é exatamente essa: um client React que conversa com o AkôFlow Engine.
Vamos manter dependências limpas e bem conhecidas (React, React Router, etc.), evitando acoplamentos desnecessários.

Hoje já existem APIs funcionando que a interface consome (listar workflows, criar workflows, acompanhar execução, etc.), então temos uma boa base para evoluir rapidamente.

Fica o convite:
Se quiser participar da estruturação inicial do projeto (arquitetura, stack, padrões, CI básico), será muito bem-vindo.

O que você acha desse caminho?