Especificação Técnica
Arquitetura Node.js + React
Especificação detalhada da arquitetura técnica da plataforma DBCHECKOUT
Versão 1.0•Última atualização: Janeiro 2025
1Arquitetura Lógica em Camadas
Camada de Dados
- • MySQL Legado (Lojas)
- • PostgreSQL Analítico
- • Redis Cache
- • Staging Area
Camada de Aplicação
- • API REST (Node.js)
- • ETL Engine
- • Auth Service (JWT)
- • AI Orchestrator
Camada de Apresentação
- • React SPA
- • Dashboard UI
- • Mobile Responsive
- • WebSocket Client
Princípio de Separação
Cada camada possui responsabilidades claras e isoladas. A camada de dados legados nunca é modificada. Toda transformação ocorre na camada de aplicação, e os dados consolidados são armazenados no banco analítico.
2Responsabilidades do Backend Node.js
Autenticação e Autorização
Gerenciamento completo de identidade, sessões e controle de acesso.
- • Emissão e validação de JWT (Access + Refresh Tokens)
- • RBAC (Role-Based Access Control) por rede, loja e perfil
- • Middleware de autorização em todas as rotas protegidas
- • Gestão de sessões e logout distribuído
- • Rate limiting e proteção contra brute force
ETL e Consolidação de Dados
Ingestão, transformação e consolidação de dados legados.
- • Conexão read-only com bancos MySQL legados
- • Queries SQL otimizadas sem ORM obrigatório
- • Transformação de dados operacionais em KPIs analíticos
- • Agendamento de jobs (EOD, turno, manual)
- • Validação, deduplicação e tratamento de erros
- • Logs detalhados de auditoria e rastreabilidade
API REST Analítica
Endpoints para consulta de KPIs, dashboards e relatórios.
- • Endpoints RESTful versionados (/api/v1/...)
- • Filtros avançados (período, loja, hierarquia de produtos)
- • Paginação, ordenação e agregações
- • Cache inteligente com Redis (TTL configurável)
- • Compressão de respostas (gzip/brotli)
- • Documentação automática (Swagger/OpenAPI)
Orquestração de IA
Integração com modelos de ML para geração de insights.
- • Preparação de payloads estruturados (JSON com KPIs)
- • Chamadas assíncronas para APIs de IA (OpenAI, Claude, etc.)
- • Processamento e validação de respostas da IA
- • Armazenamento de insights gerados
- • Detecção de anomalias e alertas automáticos
- • Isolamento total: IA nunca acessa bancos legados
WebSocket e Real-time
Comunicação bidirecional para atualizações em tempo real.
- • WebSocket server (Socket.io ou ws)
- • Notificações de novos insights de IA
- • Atualização de KPIs em tempo real
- • Alertas de anomalias e eventos críticos
- • Sincronização de estado entre múltiplos clientes
Logs, Auditoria e Monitoramento
Rastreabilidade completa de operações e performance.
- • Logs estruturados (Winston, Pino)
- • Auditoria de acessos e operações sensíveis
- • Métricas de performance (Prometheus, Grafana)
- • Health checks e readiness probes
- • Error tracking (Sentry, Rollbar)
3Responsabilidades do Frontend React
Interface de Usuário
- • Componentes reutilizáveis e modulares (Atomic Design)
- • Design System consistente (cores, tipografia, espaçamentos)
- • Responsividade total (Mobile-first approach)
- • Acessibilidade (WCAG 2.1 AA)
- • Animações e transições suaves
Dashboards e Visualizações
- • Gráficos interativos (Recharts, Chart.js, D3.js)
- • Tabelas com ordenação, filtros e paginação
- • Drill-down hierárquico (Grupo → Tipo → Tamanho → Produto)
- • Filtros avançados (período, loja, categoria)
- • Exportação de dados (CSV, Excel, PDF)
Gerenciamento de Estado
- • Context API para estado global (auth, user, theme)
- • React Query para cache e sincronização de dados
- • Local state para componentes isolados
- • Persistência em localStorage (preferências, filtros)
- • Otimistic updates para melhor UX
Roteamento e Navegação
- • React Router para SPA navigation
- • Rotas protegidas com guards de autenticação
- • Lazy loading de páginas e componentes
- • Breadcrumbs e navegação contextual
- • Deep linking para compartilhamento de views
Performance e Otimização
- • Code splitting e tree shaking
- • Memoization (useMemo, useCallback, React.memo)
- • Virtualização de listas longas (react-window)
- • Debounce em inputs de busca e filtros
- • Service Worker para cache offline
Tratamento de Erros e Feedback
- • Error boundaries para captura de erros React
- • Toasts e notificações para feedback de ações
- • Loading states e skeletons
- • Mensagens de erro amigáveis e acionáveis
- • Retry automático em falhas de rede
4Comunicação Frontend ↔ Backend
Protocolo HTTP/HTTPS
- • REST API como protocolo principal
- • JSON como formato de dados
- • HTTPS obrigatório em produção
- • CORS configurado para domínios autorizados
- • Content-Type: application/json
Autenticação em Requisições
Authorization: Bearer <access_token>
- • Access Token enviado em todas as requisições protegidas
- • Refresh Token usado para renovação automática
- • Interceptor Axios para injeção automática do token
- • Logout automático em caso de token inválido (401)
WebSocket para Real-time
- • Conexão WebSocket após autenticação bem-sucedida
- • Eventos:
kpi:update,insight:new,alert:anomaly - • Reconexão automática em caso de queda
- • Heartbeat para manter conexão ativa
Padrão de Resposta
{
"success": true,
"data": { ... },
"meta": {
"page": 1,
"limit": 20,
"total": 150
},
"timestamp": "2025-01-15T10:30:00Z"
}
5Autenticação e Autorização (JWT + RBAC)
Fluxo de Autenticação JWT
1
Login
Usuário envia credenciais (email + senha) via POST /api/v1/auth/login
2
Validação
Backend valida credenciais e verifica permissões (rede, loja, perfil)
3
Emissão de Tokens
Backend gera Access Token (15min) e Refresh Token (7 dias)
4
Armazenamento
Frontend armazena tokens em memória (Context) e Refresh Token em httpOnly cookie
5
Requisições Autenticadas
Todas as requisições incluem Access Token no header Authorization
6
Renovação Automática
Ao expirar Access Token, frontend usa Refresh Token para obter novo par de tokens
RBAC - Controle de Acesso Baseado em Papéis
Admin Rede
- • Acesso total a todas as lojas
- • Gestão de usuários e permissões
- • Configuração de integrações
- • Relatórios executivos
Gestor Loja
- • Acesso apenas à sua loja
- • Dashboards operacionais
- • KPIs de vendas e produtos
- • Insights de IA da loja
Analista
- • Acesso somente leitura
- • Exportação de dados
- • Drill-down avançado
- • Relatórios customizados
Segurança do JWT
- • Tokens assinados com algoritmo HS256 ou RS256
- • Secret key armazenada em variável de ambiente
- • Payload contém: userId, networkId, storeIds[], role, permissions[]
- • Validação de expiração em cada requisição
- • Blacklist de tokens revogados (Redis)
6Estratégia de Escalabilidade
API Stateless
Backend Node.js sem estado de sessão, permitindo escalabilidade horizontal.
- • Múltiplas instâncias da API atrás de load balancer
- • Sessões gerenciadas via JWT (sem armazenamento server-side)
- • Auto-scaling baseado em CPU/memória (Kubernetes, ECS)
- • Health checks para remoção de instâncias não saudáveis
Cache Distribuído (Redis)
Redução de carga no banco analítico e melhoria de performance.
- • Cache de KPIs frequentes (TTL: 5-15 minutos)
- • Cache de hierarquia de produtos (TTL: 1 hora)
- • Cache de configurações de rede/loja (TTL: 30 minutos)
- • Invalidação inteligente após consolidação ETL
- • Redis Cluster para alta disponibilidade
Filas de Processamento
Processamento assíncrono de tarefas pesadas.
- • Bull (Redis-based) ou RabbitMQ para filas
- • Jobs de ETL executados em workers dedicados
- • Geração de relatórios em background
- • Processamento de insights de IA assíncrono
- • Retry automático com backoff exponencial
Sharding do Banco Analítico
Particionamento de dados para suportar centenas de lojas.
- • Sharding por networkId (cada rede em shard separado)
- • Particionamento temporal de KPIs (por mês/ano)
- • Read replicas para queries analíticas pesadas
- • Connection pooling otimizado
CDN e Edge Caching
Distribuição global de assets estáticos.
- • Frontend React servido via CDN (CloudFront, Cloudflare)
- • Cache de assets estáticos (JS, CSS, imagens)
- • Compressão gzip/brotli
- • HTTP/2 e HTTP/3 para melhor performance
7Estratégia de Segurança
Proteção de Dados
- • Criptografia em trânsito: HTTPS/TLS 1.3 obrigatório
- • Criptografia em repouso: Dados sensíveis criptografados no banco
- • Senhas: Hash com bcrypt (salt rounds: 12)
- • Secrets: Variáveis de ambiente, nunca hardcoded
- • PII: Dados pessoais anonimizados em logs
Proteção contra Ataques
- • SQL Injection: Queries parametrizadas, validação de inputs
- • XSS: Sanitização de outputs, CSP headers
- • CSRF: Tokens CSRF em formulários
- • DDoS: Rate limiting, WAF (Cloudflare, AWS Shield)
- • Brute Force: Limite de tentativas de login, captcha
Isolamento Multi-tenant
- • Cada rede possui dados completamente isolados
- • Validação de networkId em todas as queries
- • Row-level security no banco analítico
- • Auditoria de acessos cross-tenant
- • Testes automatizados de isolamento
Auditoria e Compliance
- • Logs de auditoria para todas as operações sensíveis
- • Rastreabilidade completa (quem, quando, o quê)
- • Conformidade com LGPD (Brasil) e GDPR (Europa)
- • Retenção de logs por período regulatório
- • Relatórios de acesso para compliance
Segurança do Banco Legado
- • Conexões read-only com usuário de banco limitado
- • Timeout configurado para evitar queries longas
- • Whitelist de IPs para acesso ao banco legado
- • VPN ou túnel SSH para conexões remotas
- • Monitoramento de queries suspeitas
Especificação Técnica
DBCHECKOUT - Arquitetura Node.js + React v1.0