Documentação Técnica e Arquitetural Interna — Gatein
Classificação: Interno — Restrito à equipe de engenharia
Status Global: 🟢 Ativo / Atualizado
Versão: 2.0.0
Última Revisão Técnica: 2026-08-03
1. Propósito e Visão Geral da Plataforma
Este repositório contém a especificação arquitetural canônica e exaustiva do ecossistema Gatein. O Gatein é a plataforma de alta performance desenvolvida para orquestrar e automatizar a recepção, triagem, agendamento e liberação de veículos pesados (carretas e caminhões de carga) em Terminais Marítimos, Portos Secos, Armazéns Logísticos e Transportadoras.
O sistema elimina filas físicas e senhas impressas ao integrar:
- Aplicativo Mobile (React Native): Interface nativa utilizada pelos motoristas para recepção de ordens de carga, check-in antecipado por Geofence e exibição do Ticket Digital com código QR.
- Painel Web (React / Vite): Console de gestão operacional multi-tenant para Operadores de Pátio e Transportadoras definirem janelas, layouts, geofences e aprovação de entrada.
- Backend de Alta Disponibilidade (FastAPI): Servidor assíncrono em Python responsável pela máquina de estados, orquestração Socket.IO com totens de pátio, envio de push FCM e controle de segurança.
2. Mapeamento dos Repositórios do Ecossistema
| Repositório | Stack Principal | Papel no Ecossistema |
|---|---|---|
gatein-server | Python 3.11+, FastAPI, SQLAlchemy, Redis, APScheduler | API REST, comunicação WebSocket Socket.IO com hardware local de pátio, envio em lote de FCM Push, engine de regras e banco PostgreSQL. |
gatein-app | React Native, Zustand, Mapbox GL, Notifee, SecureStorage | Aplicativo nativo iOS e Android para motoristas de frete. Suporta Geofencing em background e renderização de tickets em brilho máximo. |
gatein-web | React 18, Vite, React Router v6, Firebase Auth Web | Console administrativo para Terminais/Transportadores. Contém editores visuais de layout, mapas de geofence, gestão de usuários e aprovações. |
gatein-docs | Docusaurus | Portal de documentação pública, manuais de homologação e guias de integração API para clientes. |
gatein-docs-internal | Docusaurus | Este repositório — Especificação interna detalhada, regras de negócio RN-XXX, modelos SQL e contratos da API. |
3. Convenções e Padronização da Engenharia
3.1 Identificadores de Status dos Módulos
- 🟢 Implementado: Funcionalidade em produção com cobertura total de testes e regras validadas.
- 🟡 Parcial: Funcionalidade parcialmente implementada ou com recursos avançados em desenvolvimento.
- 🔵 Planejado: Especificação aprovada em arquitetura, porém pendente de codificação.
- 🔴 Depreciado: Componente ou endpoint substituído por versões mais recentes.
3.2 Formato Padrão das Regras de Negócio (RN-XXX)
Todas as regras de negócio deste ecossistema são categorizadas e referenciadas sob o código único RN-[MÓDULO]-[NÚMERO]:
RN-AUT-XXX: Autenticação e Onboarding de Motorista no App Mobile.RN-WEB-AUTH-XXX: Autenticação Híbrida e Sessões do Web App.RN-APT-XXX/RN-APT-WEB-XXX: Regras de Agendamento e Janelas Temporais.RN-CHK-XXX: Handshake Socket.IO, Timeouts e Check-in Antecipado.RN-TKT-XXX: Imutabilidade de Tickets e Renderização Óptica.RN-GEO-XXX: Perímetros Geográficos e Validação Server-Side.RN-LAY-XXX: Dynamic Layout Engine e Sincronização Bidirecional.RN-SEC-XXX: Treinamentos de Segurança e Rastreamento LGPD.RN-KEY-XXX: API Keys Server-to-Server e Rotação Zero-Downtime.RN-HOM-XXX: Isolamento de Testes e Staging Passwords.
4. Glossário de Domínio da Plataforma
| Termo do Domínio | Definição Técnica |
|---|---|
| Terminal | Empresa cliente dona do pátio ou armazém físico onde ocorrem as operações de carga e descarga. |
| Transportador | Empresa proprietária ou gestora de frotas que vincula motoristas a agendamentos de frete. |
| Motorista | Usuário final do aplicativo mobile, identificado compulsoriamente por seu CPF (tax_id). |
| Appointment | Compromisso operacional agendado contendo janela temporal de atendimento, placa do veículo e carga. |
| Check-in Antecipado | Confirmação remota de presença solicitada pelo motorista ao cruzar a geofence ou via app. |
| Ticket Digital | Comprovante de autorização com snapshot imutável em JSONB contendo QR Code para liberação em gate. |
| Geofence | Polígono ou círculo de coordenadas GPS associado a um terminal para disparo proativo de eventos. |
| Layout Engine | Motor dinâmico que interpreta árvores de layout JSON (layout_ref) para desenhar cards e tickets no React Native. |
| Sqid | Identificador ofuscado gerado via algoritmo Sqids para ocultar IDs sequenciais de banco de dados em respostas públicas. |
| Tenant | Empresa cliente isolada no banco relacional; todas as consultas filtram obrigatoriamente por company_id. |
| Staging Password | Senha mestre de homologação que bypassa a verificação de dispositivo e injeta coordenadas de teste. |
5. Princípios Arquiteturais Orientadores
- Isolamento Absoluto de Tenants: Nenhuma consulta SQL ou rota REST pode vazar dados entre empresas distintas. O
company_idé resolvido no backend a partir do token verificado. - Autoridade Server-Side de Localização: O aplicativo mobile envia coordenadas GPS, mas o servidor FastAPI é o único juiz elegível para determinar se o veículo está dentro do perímetro da geofence.
- Resiliência e Tolerância a Falhas em Gates: O handshake Socket.IO com os totens físicos de pátio possui timeout estrito de 15,0s com fallback automático para envio de push FCM.
- Imutabilidade Auditável de Tickets: O conteúdo impresso visualmente em um Ticket Digital é congelado no ato de aprovação do check-in, garantindo valor jurídico e segurança de auditoria.