Por Dentro do Helix: Lições de Arquitetura de um ERP Fiscal em Produção

Todo sistema de gestão promete a mesma coisa: organizar o caos de uma operação real dentro de telas e formulários. Poucos são cobrados por isso com a mesma dureza que um ERP brasileiro. Aqui não existe margem para "quase certo" — uma nota fiscal mal emitida vira multa, um centavo perdido em arredondamento vira divergência de caixa, uma tela que trava no meio de um pedido vira fila no caixa.

O Helix — um ERP de varejo e retaguarda fiscal construído em Angular, hoje na versão 10.1 — nasceu para operar exatamente nessa margem estreita. A forma como foi construído, não apenas o que ele faz, é o material mais valioso para quem está prestes a abrir uma pasta vazia e começar um projeto sério.

Em números: 826 arquivos TypeScript, 217 componentes próprios de interface, 49 serviços dedicados de domínio, distribuídos em cerca de 20 módulos de negócio isolados.

O mapa antes do território

A primeira decisão que se sente ao abrir o código do Helix não é técnica, é organizacional: vendas, notas fiscais, financeiro, estoque, compras, requisições, devoluções, MDF-e, SPED e cadastro de pessoas vivem cada um em seu próprio módulo de rotas, com seus próprios serviços e seus próprios modelos. Nenhum deles conhece os detalhes internos do outro — conversam por serviços expostos, nunca por acesso direto a estado alheio.

Isso é, na prática, um monólito modular: uma única aplicação que se comporta como se fosse composta de vários times de domínio trabalhando lado a lado. A lição para quem está começando agora não é "use microsserviços" nem "use uma pasta por tela" — é desenhar as fronteiras de negócio antes das fronteiras de pasta. Um pedido de venda, uma nota fiscal e um lançamento financeiro são conceitos diferentes, com ciclos de vida diferentes, e o código deveria deixar isso óbvio antes mesmo de abrir um arquivo.

Cada domínio expõe seu próprio módulo de rotas e é protegido por um guard de autenticação antes mesmo de a interface carregar o componente — a permissão de acesso não é um detalhe de tela, é uma regra de rota.

Um design system que não se reinventa a cada tela

Um ERP tem dezenas de telas de cadastro, listagem e detalhe que devem parecer a mesma coisa. O Helix resolve isso com um vocabulário de componentes próprios — botões, caixas, abas, seletores, campos de moeda, indicadores de status — declarados em um único ponto central da aplicação, todos com o mesmo prefixo de nomenclatura.

Construir a terceira tela é rápido quando a primeira e a segunda já pagaram o custo de criar um sistema de componentes. É lento, e cada vez mais lento, quando cada tela reinventa seu próprio botão.

Esse é talvez o investimento mais subestimado por quem começa um projeto novo — e a convenção de nomes consistente, aparentemente estética, é o que permite a qualquer desenvolvedor encontrar o componente certo sem depender de memória ou de documentação desatualizada.

Uma porta única para entrar, uma única para falhar bem

Toda chamada ao backend do Helix passa por um único interceptor HTTP. É ali, e só ali, que o token de autenticação é anexado ao cabeçalho da requisição, que uma sessão expirada é detectada, e que uma queda de conexão é distinguida de um erro de regra de negócio. Nenhuma tela precisa se lembrar de tratar isso — a decisão foi centralizada uma vez, no nível certo da arquitetura.

O mesmo raciocínio aparece na proteção de formulários: um guard genérico de saída de rota impede que o usuário perca um pedido de venda pela metade só porque clicou no botão errado do menu — uma linha de código por formulário para evitar o pior tipo de bug: aquele que destrói o trabalho de alguém sem avisar.

Todo endpoint do backend está reunido em um único arquivo de referência com pouco mais de 500 linhas — o mapa completo da API em um só lugar, em vez de espalhado por dezenas de serviços.

Além do CRUD: quando o sistema precisa de reflexo

Boa parte do que se ensina sobre desenvolvimento web para de fazer sentido no chão de uma loja. Uma nota fiscal eletrônica não é autorizada no instante em que é enviada — ela viaja até a Sefaz, é validada, e só depois volta com o carimbo de autorizada ou rejeitada. Uma balança de pesagem gera um evento físico que o sistema precisa capturar. Um pedido fechado no caixa precisa sair impresso sem que o operador espere olhando para uma tela travada.

O Helix resolve essa classe de problema com canais dedicados de tempo real sobre SignalR — um para notificações gerais, outro específico para o ciclo de vida fiscal das notas — em vez de forçar tudo a caber no padrão requisição-resposta do HTTP. E trata a impressão como preferência do terminal físico, não da conta do usuário: cada caixa da loja guarda sua própria configuração de impressora, independente de quem está logado nele.

Dinheiro não aceita arredondamento

Ponto flutuante e cálculo financeiro não se dão bem — qualquer desenvolvedor que já viu um centavo sumir num rateio de desconto sabe disso. O Helix isola essa aritmética num módulo próprio, separado da lógica de tela, para que a regra de arredondamento de um desconto rateado entre itens de pedido seja escrita, revisada e corrigida em um único lugar.

Nem tudo no projeto é exemplo a seguir sem ressalva, e essa honestidade também é know-how: os validadores de formulário existem em três gerações lado a lado, sinal de sucessivas extensões sem coragem de migrar a anterior. A lição para quem começa agora é justamente essa — quando perceber que está prestes a criar uma "versão 2" de um utilitário, é hora de parar e migrar o que já existe, não empilhar mais uma camada.

O que fica, em forma de checklist

Nenhum destes pontos é exclusivo de um ERP. São decisões de engenharia que valem para o primeiro commit de qualquer projeto que pretenda crescer além de um protótipo de fim de semana.

Infraestrutura de testes que existe na configuração mas não é usada é uma dívida que só fica mais cara com o tempo. No Helix, essa disciplina aparece em 22 suítes de teste com 270 casos e 96% de cobertura no núcleo — escrever testes antes que o primeiro módulo vire vinte é o tipo de decisão que só fica mais difícil de tomar quanto maior a base de código.