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
- O
akoflow-admin executa npm run build, produzindo uma pasta estática (ex.: dist/).
- O
akoflow-engine, ao ser compilado, incorpora ou referencia essa pasta.
- 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:
-
Branch dedicada (ex.: feature-vite-akoflow-admin):
- Evita exposição prematura de uma interface incompleta.
- Facilita reverts caso a proposta não avance.
-
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.
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:
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:
test,lint,build);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:
Nesse formato:
akoflow-enginemantém o projeto Go e as funcionalidades centrais;akoflow-adminmantém o projeto Vite + React e toda a lógica da interface administrativa.O
akoflow-enginecontinuaria servindo o AkôFlow Admin, mas agora servindo arquivos estáticos, sem qualquer interpolação dinâmica.Fluxo
akoflow-adminexecutanpm run build, produzindo uma pasta estática (ex.:dist/).akoflow-engine, ao ser compilado, incorpora ou referencia essa pasta./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:
Branch dedicada (ex.:
feature-vite-akoflow-admin):Duas versões lado a lado, controladas por feature flag (minha preferência):
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:
akoflow-admin(npm install);lint,test, etc.);npm run build);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.