Pular para o conteúdo principal

Visão Geral da Arquitetura do Sistema

Pilar: 01 — Arquitetura, Stack e Segurança
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server, gatein-app, gatein-web

1. Diagrama de Componentes do Ecossistema​

O ecossistema Gatein é composto por uma arquitetura distribuída e desacoplada baseada em serviços RESTful, comunicação bidirecional em tempo real (Socket.IO) e infraestrutura de nuvem Serverless/Firebase:

graph TB
    subgraph "Campos e Clientes Front-end"
        MOB["Gatein Mobile App<br/>(React Native / iOS & Android)"]
        WEB["Gatein Web App<br/>(React 18 + Vite / SPA)"]
        ERP["ERP / TMS Terceiros<br/>(SAP, TOTVS, WMS)"]
    end

    subgraph "Serviços de Infraestrutura Cloud"
        FBA["Firebase Auth<br/>(Provedor de Identidade Web)"]
        FCM["Firebase Cloud Messaging<br/>(Push Notifications Mobile)"]
        FBS["Firebase Storage<br/>(Uploads de Mídia e Fotos)"]
    end

    subgraph "Core Backend Services (gatein-server)"
        API["FastAPI App Server<br/>(Uvicorn / ASGI Async Engine)"]
        SIO["Socket.IO Server<br/>(Namespace /checkin)"]
        SCH["APScheduler Engine<br/>(Lembretes & Expurgos Background)"]
    end

    subgraph "Persistência e Cache"
        PG[(PostgreSQL 15+<br/>Banco Relacional Multi-Tenant)]
        RDS[(Redis 7+<br/>OTP Cache, Active Sockets & Jobs)]
    end

    subgraph "Automação de Pátio (Physical Gate)"
        HW["Hardware / Totem de Entrada<br/>(Leitores Ópticos & Cancelas)"]
    end

    MOB -->|REST HTTPs / JWT Mobile| API
    WEB -->|REST HTTPs / Bearer Firebase| API
    ERP -->|REST HTTPs / Header X-API-Key| API
    
    WEB -->|Auth Login| FBA
    API -->|Verify ID Token| FBA
    API -->|Dispatch Push Notifications| FCM
    FCM -->|Push Message| MOB
    
    API -->|Read/Write Records| PG
    API -->|Setex OTP / Cache Sqids| RDS
    SIO -->|Active Terminals Mapping| RDS
    
    SIO <-->|WebSocket Bidirecional / Handshake 15s| HW
    SCH -->|Verify Windows & Triggers| PG

2. Diagrama de Atores e Fluxos Operacionais​

sequenceDiagram
    autonumber
    actor M as Motorista (Mobile)
    actor T as Operador de Terminal (Web)
    actor TR as Transportador (Web)
    actor PA as Platform Admin (System)
    participant S as Gatein Server (FastAPI)

    rect rgb(240, 248, 255)
    note over TR, S: 1. Gestão de Viagens
    TR->>S: POST /web/trips (Aloca motorista e caminhão)
    end

    rect rgb(255, 250, 240)
    note over T, M: 2. Agendamento e Recepção
    T->>S: POST /web/appointments (Define janela operacional)
    S-->>M: FCM Push: "Novo Agendamento Disponível"
    end

    rect rgb(240, 255, 240)
    note over M, T: 3. Check-in e Liberação
    M->>S: POST /mobile/checkin/{terminal_id} (Entrada Geofence)
    S-->>T: Socket.IO: Notifica painel de pátio em tempo real
    T->>S: POST /web/checkin/approve (Aprova entrada)
    S-->>M: Emite Ticket Digital com QR Code no celular
    end

    rect rgb(255, 240, 255)
    note over PA, S: 4. Governança e Homologação
    PA->>S: POST /admin/system/staging-passwords (Configura senhas de teste)
    end

3. Padrão Multi-Tenant e Isolamento de Dados​

Toda a arquitetura de banco de dados do Gatein é estruturada em torno do conceito de Multi-Tenancy por Isolamento Lógico (company_id):

  1. Garantia por Injeção de Dependências: No backend FastAPI, a dependência get_current_admin_company_user ou require_permission extrai a identidade do usuário a partir do token verificado e descobre o seu company_id.
  2. Filtro Obrigatório em Queries: Nenhuma instrução SQL de consulta, atualização ou deleção no PostgreSQL pode ser executada sem a cláusula explícita: WHERE company_id = current_user.company_id
  3. Proteção Contra Escalada Horizontal de Privilégios: Mesmo que um atacante altere os identificadores na URL da requisição Web (ex: /web/appointments/123), a query intercepta e valida se a entidade pertence à empresa do token autenticado. Se não pertencer, retorna HTTP 404/403.

4. Fronteiras de Responsabilidade e Contratos de Serviço​

ComponenteResponsabilidade ExclusivaO que NÃO é de sua alçada
gatein-serverMáquina de estados operacionais, validações de janela, geração de tokens JWT, emissão de tickets, cálculo geográfico de geofences e despacho FCM.Interface do usuário e captura de sinal de sensores GPS brutos.
gatein-appCaptura de coordenadas GPS, armazenamento de tokens em local seguro, notificação via Notifee, elevação de brilho para QR Code e renderização via Dynamic Layout Engine.Decisão sobre autorização de entrada ou alteração de status de banco de dados.
gatein-webInterface gráfica de gestão, editor visual de layouts, mapa de geofence, gerenciamento de API Keys e botões de aprovação/rejeição de pátio.Armazenamento primário de credenciais de motorista.
APSchedulerMonitoramento assíncrono de janelas temporais de agendamentos, disparos de lembretes e tarefas de expurgo de logs antigos.Processamento de requisições REST síncronas de usuários.

5. Decisões Arquiteturais Registradas (ADRs)​

ADR-001: Escolha do Framework FastAPI (Python) para o Backend​

  • Contexto: Necessidade de alta capacidade de concorrência I/O (WebSocket Socket.IO, integrações REST, banco relacional) e suporte a digitação estrita com Pydantic.
  • Decisão: Utilizar FastAPI com Uvicorn (ASGI engine).
  • Consequência: Excelente throughput assíncrono, documentação automática OpenAPI/Swagger e serialização rápida.

ADR-002: Utilização de Sqids para Ofuscação de IDs​

  • Contexto: Impedir que concorrentes ou usuários mal-intencionados enumerem a quantidade de agendamentos, motoristas ou tickets do sistema alterando IDs numéricos sequenciais em URLs (/activities/1, /activities/2).
  • Decisão: Adotar a biblioteca Sqids para codificar IDs numéricos e UUIDs em strings alfanuméricas ofuscadas.
  • Consequência: IDs públicos legíveis e seguros; o banco armazena chaves nativas e a API serializa/deserializa via encode_id() e decode_id().

ADR-003: Snapshot Imutável de Tickets Digitais (JSONB)​

  • Contexto: Garantir que comprovantes de entrada no pátio não sofram alteração retroativa se o ERP do terminal modificar dados do agendamento após a liberação.
  • Decisão: No ato da aprovação do check-in, o servidor gera uma foto congelada (snapshot) de todas as variáveis do ticket e persiste no campo content (JSONB) da tabela tickets.
  • Consequência: Garantia de auditoria e valor jurídico à liberação emitida ao motorista.

ADR-004: Handshake Socket.IO de 15 Segundos com Fallback FCM​

  • Contexto: A comunicação com totens físicos e leitores de pátio pode falhar devido a instabilidades de rede local no terminal.
  • Decisão: Definir timeout de 15,0s na chamada RPC sio.call('request_checkin'). Se o totem não responder, dispara evento assíncrono FCM com notificação de falha para o dispositivo do motorista.
  • Consequência: Evita travamentos de conexões HTTP no celular do motorista e provê feedback claro em caso de indisponibilidade de pátio.