Stack Tecnológico e Dependências

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. Visão Geral da Stack por Camada

O ecossistema Gatein é construído sobre tecnologias consolidadas de mercado, priorizando performance assíncrona, desacoplamento e suporte a múltiplos dispositivos.

graph LR
    subgraph "Mobile App (gatein-app)"
        RN[React Native Bare]
        ZUS_M[Zustand Store]
        MBX[Mapbox GL]
        NOT[Notifee + FCM]
    end

    subgraph "Web App (gatein-web)"
        RCT[React 18 + Vite]
        ZUS_W[Zustand Store]
        FBA_W[Firebase Auth Web]
    end

    subgraph "Server Backend (gatein-server)"
        FAP[FastAPI + Uvicorn]
        SQL[SQLAlchemy ORM]
        APS[APScheduler]
        FBA_S[Firebase Admin SDK]
    end

    subgraph "Infraestrutura & Persistência"
        PG[(PostgreSQL 15+)]
        RDS[(Redis 7+)]
        FBS[Firebase Cloud Services]
    end

    RN --> FAP
    RCT --> FAP
    FAP --> PG
    FAP --> RDS
    FAP --> FBS

---

2. Especificação do Backend (gatein-server)

Componente	Tecnologia / Library	Versão	Propósito no Sistema
Runtime & Liguagem	Python	3.11.x	Ambiente de execução com suporte nativo a asyncio de alta performance.
Framework Web	FastAPI	0.104.x	Framework ASGI rápido para construção de APIs REST e documentação Swagger nativa.
Servidor ASGI	Uvicorn	0.24.x	Servidor de aplicação de produção assíncrono.
ORM / Database Access	SQLAlchemy	2.0.x	Mapeador objeto-relacional declarativo com suporte a queries assíncronas.
Gerenciador de Migrações	Alembic	1.12.x	Controle de versionamento do schema do banco PostgreSQL.
Banco Relacional	PostgreSQL	15.x	Banco de dados primário multi-tenant com suporte a colunas JSONB.
Cache & Pub/Sub	Redis	7.x	Armazenamento temporário de OTPs, gerenciamento de sessões Socket.IO e JobStore.
Scheduler Assíncrono	APScheduler	3.10.x	Agendador de jobs de fundo, lembretes de agendamento e limpezas LGPD.
Comunicação WebSockets	python-socketio	5.10.x	Servidor WebSocket Socket.IO para comunicação em tempo real com hardware de pátio.
Provedor Push / Auth	firebase-admin	6.2.x	SDK de validação de tokens Firebase e despacho de notificações FCM em massa.
Ofuscação de IDs	Sqids	0.4.x	Algoritmo de geração de hashes alfanuméricos curtos para IDs numéricos e UUIDs.
Criptografia & Hash	Passlib / Bcrypt	1.7.x	Criptografia segura de senhas de usuários e hashes de API Keys.

---

3. Especificação do App Mobile (gatein-app)

Componente	Tecnologia / Library	Versão	Propósito no Sistema
Framework Mobile	React Native (Bare Workflow)	0.72.x	Desenvolvimento nativo cruzado (Android & iOS) de alta performance.
Linguagem	JavaScript (JSX) / TypeScript	ES2022	Linguagem de desenvolvimento dos componentes e telas.
Gerenciador de Estado	Zustand	4.4.x	Gerenciamento de estado global leve e previsível sem boilerplate.
Navegação	React Navigation	v6	Roteamento nativo de telas (Stack & Tab Navigators).
Mapas e Geofence Visual	Mapbox GL (@rnmapbox/maps)	10.x	Renderização vectorial de mapas, marcadores de pátio e visualização de geofences.
Notificações Nativas	Notifee	7.8.x	Exibição avançada de notificações no tray do sistema operacional.
Messaging Client	@react-native-firebase/messaging	18.x	Listener de notificações push FCM em foreground, background e quit states.
HTTP Client	Axios	1.6.x	Cliente HTTP com interceptors para injeção automática de token Bearer.
Armazenamento Seguro	react-native-encrypted-storage	4.0.x	Armazenamento de tokens JWT no Keychain (iOS) e Keystore (Android).
Controle de Tela/Brilho	expo-brightness / expo-keep-awake	11.x	Mantém a tela acesa e eleva o brilho a 100% durante a exibição do QR Code do Ticket.

---

4. Especificação do Web App (gatein-web)

Componente	Tecnologia / Library	Versão	Propósito no Sistema
Framework Frontend	React	18.2.x	Biblioteca de construção de interfaces declarativas em componentes.
Build Tool / Bundler	Vite	5.x	Ferramenta de build ultra-rápida e ambiente de desenvolvimento HMR.
Roteamento	React Router DOM	v6.20	Gerenciamento de rotas e rotas protegidas por permissões (RBAC).
Gerenciador de Estado	Zustand	4.4.x	Store central com persistência de dados do usuário autenticado.
Autenticação Client	Firebase Web SDK (firebase/auth)	10.x	Conexão direta com o Firebase Auth para login por e-mail e senha.
Editor de Layouts / JSON	Monaco Editor / JSON Tree	0.44.x	Editor visual e de código com validação sintática para schemas de layout.

---

5. Matriz de Compatibilidade e Requisitos de Sistema

gantt
    title Compatibilidade de Runtime e Plataformas
    dateFormat  YYYY-MM-DD
    section Backend
    Python 3.11+             :active, p1, 2026-01-01, 2028-12-31
    PostgreSQL 15+           :active, p2, 2026-01-01, 2028-12-31
    Redis 7+                 :active, p3, 2026-01-01, 2028-12-31
    section Mobile
    Android 8.0+ (API 26+)   :active, m1, 2026-01-01, 2028-12-31
    iOS 14.0+                :active, m2, 2026-01-01, 2028-12-31
    section Tooling
    Node.js 18 LTS           :active, t1, 2026-01-01, 2028-12-31

---

6. Regras de Segurança e Política de Credenciais

RN-STACK-001: Isolamento do Arquivo serviceAccountKey.json

O arquivo de credenciais privadas do Firebase Admin (serviceAccountKey.json) contendo a chave privada do projeto é de uso exclusivo do servidor (gatein-server). É estritamente proibido incluir ou empacotar este arquivo em builds do aplicativo mobile (gatein-app) ou web app (gatein-web).

RN-STACK-002: HTTPS/TLS Obrigatório em Produção

Em ambiente de produção (ENVIRONMENT == 'production'), todas as conexões entre o aplicativo mobile/web e o servidor FastAPI exigem obrigatoriamente transporte seguro via TLS 1.3 (HTTPS). Conexões em texto claro via http:// são recusadas pelo reverse proxy NGINX.