Pular para o conteúdo principal

ADR 0001 - Visão de Arquitetura

Introdução ao documento​

Este ADR registra uma decisão arquitetural relevante e suas consequências.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-09
  • Responsável: Marivaldo Vinicius

Referencial teórico​

Contexto​

Necessidade de construir um dashboard administrativo para agência de cursos (Dhedalos) que consolide dados de múltiplas fontes (Redshift, WordPress, AoVivo API) e forneça interface administrativa moderna com análise de sentimento e relatórios de NPS.

Requisitos principais:

  • Interface administrativa completa
  • API REST para consumo de dados
  • Integração com múltiplas fontes de dados externas
  • Análise de sentimento de textos
  • Performance otimizada para grandes volumes de dados
  • Controle de acesso baseado em roles

Decisão​

1. Stack Principal: Laravel 11 + React/TypeScript​

Utilizar Laravel 11 como backend e React/TypeScript como frontend, separando responsabilidades entre API REST e interface administrativa.

Justificativa:

  • Laravel oferece ecossistema maduro para APIs e painéis administrativos
  • React permite interface moderna e reativa
  • TypeScript adiciona segurança de tipos no frontend
  • Separação clara entre backend e frontend facilita manutenção

2. Painel Administrativo: Backpack for Laravel​

Utilizar Backpack for Laravel como framework de painel administrativo em vez de construir interface do zero.

Justificativa:

  • Acelera desenvolvimento de CRUDs e interfaces administrativas
  • Integração nativa com Laravel e Spatie Permissions
  • Interface moderna e responsiva (Tabler theme)
  • Reduz código boilerplate para operações administrativas

3. Autenticação: Laravel Sanctum + Spatie Permissions​

Utilizar Laravel Sanctum para autenticação de API e Spatie Permissions para controle de acesso baseado em roles.

Justificativa:

  • Sanctum é nativo do Laravel, sem dependências externas complexas
  • Suporta autenticação stateful (sessões) e stateless (tokens)
  • Spatie Permissions oferece sistema robusto de roles e permissões
  • Integração nativa com Backpack

4. Estrutura de Backend: API REST + Admin Controllers​

Separar controllers em duas camadas: API REST (v1) para consumo de dados e Admin Controllers para interface administrativa.

Justificativa:

  • Separação clara de responsabilidades
  • API pode ser consumida por múltiplos clientes (frontend React, integrações)
  • Admin Controllers focados em renderização de views
  • Facilita versionamento da API

5. Cache Estratégico com Compressão​

Implementar sistema de cache com compressão gzip para dados grandes (inscrições, agendamentos) e TTL variável baseado na criticidade dos dados.

Justificativa:

  • Redshift tem latência alta, cache reduz consultas diretas
  • Compressão gzip reduz uso de memória e transferência de dados
  • TTL variável (30s a 4h) balanceia frescor e performance
  • Jobs assíncronos atualizam cache sem bloquear requisições

6. Processamento Assíncrono: Laravel Queue + Supervisor​

Utilizar Laravel Queue para processamento assíncrono de cache e Supervisor para gerenciar múltiplos workers.

Justificativa:

  • Processamento de cache pode ser demorado, não deve bloquear requisições
  • Supervisor garante alta disponibilidade dos workers
  • Múltiplos processos (4 workers) aumentam throughput
  • Timeout configurável (900s) para jobs longos

7. Integração com IA: Google Gemini API​

Utilizar Google Gemini API para análise de sentimento em vez de modelos locais ou outras APIs.

Justificativa:

  • Gemini oferece modelo generativo de alta qualidade
  • API simples de integrar via pacote Laravel oficial
  • Cache de resultados reduz custos e latência
  • Flexibilidade para ajustar prompts conforme necessário

8. Servidor de Produção: FrankenPHP/Octane​

Utilizar Laravel Octane com FrankenPHP em produção para melhor performance.

Justificativa:

  • Octane mantém aplicação em memória, reduzindo overhead
  • FrankenPHP oferece melhor performance que PHP-FPM tradicional
  • Suporta aplicações de alta concorrência
  • Compatível com workers assíncronos

Consequências​

Positivas​

  • Desenvolvimento rápido: Backpack acelera criação de interfaces administrativas
  • Performance: Cache e compressão otimizam resposta para grandes volumes de dados
  • Escalabilidade: Processamento assíncrono permite lidar com cargas altas
  • Manutenibilidade: Separação clara de responsabilidades facilita manutenção
  • Flexibilidade: API REST permite múltiplos consumidores
  • Segurança: Sanctum + Spatie oferecem controle de acesso robusto

Negativas​

  • Complexidade: Múltiplas camadas (API, Admin, Jobs, Services) aumentam complexidade
  • Dependências: Backpack requer licença comercial para recursos avançados
  • Cache stale: Dados podem estar desatualizados dependendo do TTL
  • Custo de integrações: APIs externas (Gemini, AoVivo) têm custos associados
  • Overhead de compressão: CPU adicional para compressão/descompressão
  • Gestão de workers: Supervisor adiciona camada de gerenciamento

Alternativas consideradas​

Backend puro vs Backpack​

Alternativa: Construir painel administrativo do zero com Laravel + Blade/React Rejeitada porque: Desenvolvimento muito mais lento, necessidade de implementar CRUDs, autenticação e permissões manualmente

Redis Cache vs Laravel Cache​

Alternativa: Usar Redis diretamente em vez de abstração Laravel Cache Rejeitada porque: Laravel Cache oferece flexibilidade (Redis/Memcached/File) e abstração consistente

Síncrono vs Assíncrono para Cache​

Alternativa: Atualizar cache de forma síncrona nas requisições Rejeitada porque: Bloqueia requisições, especialmente para grandes volumes de dados do Redshift

Modelo de IA local vs API​

Alternativa: Usar modelo de IA local ou outras APIs (OpenAI) Rejeitada porque: Gemini oferece boa relação custo-benefício e integração simples