Resumo executivo
Este estudo de caso documenta um portal corporativo privado que evoluiu de uma base de help desk para uma plataforma interna modular.
O sistema começou com fluxos de suporte baseados no HESK. Com o tempo, a organização passou a precisar do mesmo ambiente autenticado para atender outros domínios operacionais: inventário de ativos, solicitações de manutenção, demandas de marketing, reservas de veículos e viagens, ordens de serviço, dashboards e integrações com serviços internos de infraestrutura.
Uma reescrita completa atrasaria melhorias úteis e aumentaria o risco de migração. A estratégia escolhida foi a modernização incremental: preservar o núcleo de chamados já validado, criar limites explícitos entre módulos, centralizar responsabilidades compartilhadas e introduzir APIs, migrations, deploy automatizado e observabilidade quando houvesse benefício operacional concreto.
O código-fonte, a identidade da empresa, os endereços reais, as informações de usuários, credenciais, nomes de bancos e a topologia são intencionalmente omitidos. A arquitetura e as decisões de engenharia são descritas em um nível tecnicamente útil sem expor o ambiente operacional.
Contexto
O portal atende fluxos pertencentes a diferentes departamentos e utilizados por pessoas com permissões distintas. Algumas áreas são amplamente acessíveis a usuários autenticados, enquanto outras ficam limitadas a funções específicas ou locais de rede confiáveis.
A plataforma também combina diferentes modelos de execução:
- páginas PHP servidas pelo Apache;
- sessões e convenções administrativas do HESK;
- interfaces enriquecidas com JavaScript;
- múltiplos bancos e schemas MySQL;
- serviços Python para APIs, coletores e integrações operacionais;
- anexos e configurações locais persistentes que precisam sobreviver aos deploys;
- tarefas agendadas e chamadas a serviços externos;
- runner de deploy self-hosted no ambiente de produção.
O resultado não é uma aplicação isolada. É uma superfície operacional que conecta pessoas, bancos de dados, serviços em segundo plano, evidências de infraestrutura e processos de negócio.
Problema
À medida que novos requisitos eram adicionados de forma independente, o principal risco era a fragmentação.
Sem uma arquitetura compartilhada, cada fluxo poderia se transformar em outra aplicação desconectada, com login, linguagem visual, processo de deploy, permissões, relatórios e documentação operacional próprios. Isso aumentaria o esforço de suporte e dificultaria melhorias entre módulos.
O portal precisava oferecer:
- um ponto de entrada reconhecível;
- comportamento reutilizável de autenticação e autorização;
- limites claros entre módulos;
- evolução segura de mais de um banco de dados;
- acesso controlado em diferentes contextos de rede;
- deploy e rollback reproduzíveis;
- integrações sem expor credenciais de banco aos navegadores;
- dashboards sem repetir consultas de agregação custosas em cada acesso;
- logs e evidências de saúde suficientes para troubleshooting.
Restrições
A implementação precisou operar dentro de várias restrições práticas.
O comportamento já existente em produção não podia ser descartado
A base de chamados já continha histórico operacional, anexos, usuários, categorias, permissões e processos específicos dos departamentos. Substituir tudo de uma vez criaria mais risco do que valor.
Os módulos evoluíam em velocidades diferentes
Suporte, ativos, manutenção, marketing, agendamentos e relatórios não compartilham o mesmo ciclo de releases. A arquitetura precisava permitir mudanças em uma área sem exigir o redesenho de todas as demais.
A persistência não era uniforme
Alguns módulos estendiam dados do HESK. Outros utilizavam schemas ou bancos separados. Anexos, arquivos gerados, configurações e saídas de cache também possuíam requisitos de ciclo de vida diferentes.
O deploy em produção precisava minimizar interrupções
A camada PHP normalmente podia ser atualizada sem reiniciar o Apache. Os serviços Python exigiam reinício controlado. Diretórios persistentes não podiam ser sobrescritos indiscriminadamente por um checkout do repositório.
Interno não significava irrestrito
Algumas áreas do portal podiam ser expostas por mais de um caminho de rede, mas módulos sensíveis ainda exigiam controles adicionais no servidor. As decisões de acesso não podiam depender apenas de links ocultos na interface.
Arquitetura sanitizada
O diagrama abaixo omite propositalmente hosts reais, endereços, nomes de bancos, credenciais e fronteiras de rede.
A arquitetura trata o portal PHP como camada de interação, não como o único ambiente de execução. Coletas em segundo plano e integrações são delegadas a serviços Python quando um processo persistente ou uma fronteira de API é mais adequada.
Módulos
A descrição pública agrupa os módulos privados por função, sem expor nomes internos.
Suporte e gestão de solicitações
O fluxo original de chamados permanece como base operacional. Categorias, atribuição, status, histórico, anexos e comunicação com usuários são preservados, enquanto o portal oferece uma camada mais ampla de navegação e integração.
Gestão de ativos
O módulo de ativos relaciona computadores, componentes, usuários ou responsáveis, departamentos, monitores, impressoras e regras de compatibilidade. Ele adiciona inventário estruturado sem transformar as tabelas de chamados em um schema completo de gestão patrimonial.
Fluxos departamentais de serviço
Módulos dedicados atendem áreas como manutenção, marketing, serviços gerais e ordens de serviço. Cada um aplica campos obrigatórios e permissões próprias, reutilizando a estrutura compartilhada da aplicação.
Agendamentos e reservas
Reservas e fluxos relacionados a viagens introduzem validação de datas, disponibilidade e planejamento operacional. Esses processos possuem regras diferentes da gestão de chamados, mas se beneficiam do mesmo portal autenticado.
Dashboards e relatórios
Dashboards operacionais consolidam estatísticas de chamados, carga dos departamentos, estado de backups, eventos de acesso remoto e outras evidências de infraestrutura. Eles resumem os sistemas de origem, mas não substituem sua autoridade.
Autenticação e autorização
O portal reutiliza o comportamento de autenticação e sessão do HESK quando adequado e adiciona verificações explícitas de permissão para módulos e ações customizadas.
A autorização é aplicada em vários níveis:
- se o módulo aparece na navegação;
- se a rota pode ser acessada diretamente;
- se o administrador ou usuário atual possui a capacidade necessária;
- se uma operação de criação, alteração, exclusão, exportação ou administração é permitida;
- se a requisição vem de um contexto de rede aprovado quando o módulo exige essa restrição.
A exposição consciente da rede é um controle secundário, não um substituto para identidade e permissões. Um item oculto no menu ou um endereço interno, isoladamente, não são tratados como autorização.
Estratégia multi-banco
A plataforma não força todos os domínios operacionais a compartilhar um único banco.
Essa decisão reflete a evolução do sistema: alguns módulos estendem o modelo de dados do help desk, enquanto outros possuem entidades e ciclos de release próprios. Uma camada compartilhada de bootstrap e configuração resolve a conexão adequada para cada módulo.
Os princípios principais são:
- o módulo deve ser responsável pelas tabelas que altera;
- leituras entre módulos devem ser explícitas;
- transações de negócio devem evitar dependência de escritas distribuídas entre bancos;
- relatórios podem agregar múltiplas fontes, mas os sistemas de origem continuam autoritativos;
- credenciais e valores específicos do ambiente permanecem fora do repositório público e do código entregue ao navegador.
O trade-off é uma disciplina operacional maior. Versões de schema, cobertura de backup, ordem de deploy e procedimentos de rollback precisam considerar mais de uma fronteira de persistência.
Migrations e rollback
Alterações de banco são versionadas junto ao módulo que precisa delas. Não se espera que mudanças em produção sejam aplicadas por edições manuais sem documentação.
O processo de deploy diferencia três elementos:
- arquivos da aplicação que podem ser substituídos pelo conteúdo versionado;
- arquivos persistentes que devem ser preservados;
- mudanças de schema que exigem uma etapa explícita de migration.
Nos upgrades do HESK, o fluxo também separa o updater oficial das mudanças estruturais customizadas. O schema final é validado após o upgrade do fornecedor, e somente o delta estrutural necessário é aplicado nas tabelas ou campos próprios.
O rollback é planejado antes do deploy. Conforme a mudança, ele pode incluir:
- republicar a revisão anterior da aplicação;
- restaurar configurações ou assets preservados;
- reverter uma migration quando existe uma operação de retorno segura;
- restaurar um backup do banco quando a reversão seria ambígua ou destrutiva;
- reiniciar somente o serviço Python afetado, sem reiniciar componentes web não relacionados.
Nem toda alteração de banco é reversível com segurança. Por isso, capacidade de backup e restore faz parte do projeto da migration, e não de uma etapa posterior.
Integrações e APIs
Python e FastAPI fornecem uma fronteira para tarefas que não deveriam ser executadas como lógica síncrona de uma página PHP.
Entre os casos de uso estão:
- coletar ou normalizar eventos operacionais;
- expor métricas internas para dashboards;
- ler evidências geradas de backup ou inventário;
- receber eventos autenticados de sistemas de infraestrutura;
- fornecer contratos estáveis de dados para múltiplas views do portal;
- executar agregações agendadas fora de uma requisição interativa.
Esses serviços utilizam endpoints restritos e mecanismos próprios de autenticação. Eles não expõem acesso arbitrário aos bancos nem caminhos de arquivos escolhidos pelo cliente.
O portal consome os resultados e os apresenta aos usuários, enquanto cada integração continua responsável por sua coleta e validação.
Modelo de deploy
As alterações são entregues pelo GitHub Actions a um runner self-hosted no ambiente de produção.
O fluxo de deploy é propositalmente seletivo:
- arquivos versionados da aplicação são atualizados a partir da branch aprovada;
- anexos e configurações locais persistentes são preservados;
- dependências são tratadas somente onde necessário;
- migrations são executadas como etapas explícitas;
- o backend Python é reiniciado de forma controlada;
- o Apache permanece em execução quando a atualização do PHP não exige reinício;
- logs de deploy registram a revisão e as operações aplicadas.
Esse processo substituiu um modelo sujeito a erros baseado em editar arquivos de produção diretamente e lembrar manualmente quais serviços precisavam de atenção.
Observabilidade
A plataforma registra evidências em diferentes camadas:
- erros do PHP e do servidor web;
- logs dos serviços Python;
- logs específicos das integrações;
- saída do deploy;
- estado de tarefas e serviços;
- relatórios operacionais gerados;
- atualização dos dados exibidos nos dashboards;
- endpoints de saúde dos serviços de apoio.
Consultas de relatório mais custosas podem ser isoladas atrás de cache ou saídas pré-calculadas. O cache é descartável: pode ser regenerado a partir das fontes autoritativas e não é utilizado como único registro de um evento operacional.
Essa distinção evita que uma otimização de dashboard se transforme acidentalmente em um banco de dados.
Decisões de segurança
O sistema aplica defesa em profundidade dentro dos limites de um projeto de modernização incremental.
As principais decisões incluem:
- reutilizar sessões autenticadas em vez de criar silos paralelos de identidade;
- aplicar permissões nas rotas e ações, e não apenas na navegação;
- limitar módulos selecionados pelo contexto de rede além das validações de função;
- armazenar segredos e configuração de produção fora do versionamento;
- separar o PHP exposto ao navegador das credenciais e coletores dos serviços;
- proteger arquivos persistentes durante o deploy;
- restringir integrações a contratos explícitos;
- manter logs sem gravar credenciais ou tokens;
- sanitizar screenshots, exports e documentação antes de publicação externa;
- manter o código privado e a topologia real fora do portfólio.
O sistema é interno, mas tráfego interno e usuários autenticados não são considerados automaticamente autorizados para qualquer operação.
Resultados
O projeto produziu melhorias operacionais qualitativas sem exigir uma reescrita disruptiva.
Um único ponto de entrada operacional
Os usuários acessam múltiplos fluxos por uma interface consistente, em vez de aprender aplicações e endereços independentes.
Controles reutilizáveis
Autenticação, permissões, navegação, assets compartilhados, carregamento de configuração, convenções de log e comportamento de deploy são reutilizados entre os módulos.
Evolução independente
Novos módulos podem ser adicionados ou alterados sem obrigar todos os fluxos existentes a compartilhar o mesmo schema ou ciclo de release.
Maior disciplina de deploy
Entrega versionada, migrations explícitas, preservação de dados de runtime e reinícios específicos por serviço reduzem a dependência de edições manuais em produção.
Evidências operacionais mais acessíveis
Dashboards e APIs tornam logs, estatísticas, estado de backups e eventos de infraestrutura mais fáceis de revisar, preservando a autoridade dos sistemas de origem.
Nenhum percentual de desempenho, economia, melhoria no volume de chamados ou disponibilidade é afirmado aqui, pois essas medições não foram preparadas para divulgação pública.
Aprendizados
Modernização incremental pode ser a arquitetura mais segura
Uma reescrita não é automaticamente mais limpa quando o sistema existente contém anos de comportamento operacional. Limites claros e substituições controladas entregam valor antes e reduzem o risco de migração.
Infraestrutura compartilhada exige responsabilidade explícita
Uma estrutura comum de portal é útil, mas cada módulo ainda precisa ser responsável por seu schema, permissões, integrações e comportamento de rollback.
Deploy e banco de dados são decisões conectadas
Uma mudança de schema não está completa até que ordem de deploy, janela de compatibilidade, backup e recuperação estejam definidos.
Sistemas internos também precisam de limites de confiança
Localização de rede, identidade autenticada, permissões do módulo e credenciais dos serviços respondem a perguntas de segurança diferentes. Nenhum deles deve substituir silenciosamente os demais.
Observabilidade precisa identificar a fonte autoritativa
Dashboards e caches melhoram o acesso à informação, mas devem diferenciar claramente dados de origem de resumos derivados ou atrasados.
Limitações
O sistema ainda carrega restrições herdadas de sua evolução.
- Alguns módulos seguem convenções do HESK que não foram criadas para uma plataforma mais ampla.
- Múltiplos bancos aumentam a coordenação de migrations e backups.
- A stack de produção permanece acoplada a um ambiente Apache/PHP em Windows e a um runner de deploy self-hosted.
- Os testes automatizados ainda não cobrem todos os módulos e caminhos de integração.
- Alguns dados de relatórios podem ter atraso intencional por cache ou agregação agendada.
- O portal é uma plataforma modular, não uma arquitetura completa de microserviços isolados.
Essas limitações são documentadas porque escondê-las tornaria o estudo menos útil e o modelo operacional menos seguro.
Próximos passos
A direção de longo prazo é continuar separando responsabilidades, e não realizar uma única grande reescrita.
As prioridades incluem:
- ampliar testes automatizados de permissões, migrations e contratos de API;
- padronizar eventos de saúde e auditoria por módulo;
- validar drift de schema automaticamente antes do deploy;
- melhorar a automação de rollback e os exercícios de recuperação;
- isolar ainda mais serviços persistentes do frontend web;
- centralizar observabilidade sem centralizar todos os bancos operacionais;
- continuar removendo acoplamentos legados quando houver um caminho de migração claro.
Declaração de confidencialidade
Este estudo de caso utiliza uma identidade genérica e uma arquitetura sanitizada. Ele não contém customizações restritas do HESK, código proprietário, credenciais, hostnames reais, endereços internos, registros de usuários, nomes de bancos, métricas sensíveis ou topologia de produção.