Visão Executiva: Perfil Local-Primary com Supabase

Resumo do perfil híbrido com autoridade no Postgres local e Supabase como Auth, projeção compacta e transporte de continuidade.

Escopo: esta é a visão executiva. Consulte a especificação técnica de continuidade para invariantes, estados, fencing e rollout, e a arquitetura agnóstica para entender como o perfil se encaixa no sistema multi-provider. A fundação existe no workspace, mas o failover ainda não atende rotas reais de produção.

O Desafio da Conectividade na Borda

Em cenários onde operações comerciais dependem de infraestrutura física local — como PDVs em supermercados ou terminais industriais —, a indisponibilidade do sistema local interrompe faturamentos e paralisa operações. Para contornar esse risco, implementa-se um design local-first.

No entanto, a arquitetura híbrida precisa definir claramente os limites de autoridade. Neste modelo, o Supabase Cloud não atua como backup completo nem realiza replicação multi-master. Suas responsabilidades são estritamente delimitadas a: Auth permanente, projeção de leitura compacta (snapshots) e transporte de mensagens e comandos. O banco de dados Supabase Local (self-hosted) atua como a autoridade de escrita principal para as operações enquanto estiver ativo.

Visão Geral da Arquitetura Híbrida

A topologia distribui o fluxo de dados para isolar falhas no banco local:

               ┌────────────────────────┐
               │     Supabase Cloud     │◄─── Auth Permanente
               │ (Snapshots / Fila Cmd) │◄─── Fila de Webhooks Fiscais
               └───────────▲────────────┘
                           │
                 [Transição de Estados]
                           │
               ┌───────────▼────────────┐
               │    App Server / Edge   │◄─── Valida Sessão (Auth Cloud)
               └───────────▲────────────┘
                           │
         ┌─────────────────┴─────────────────┐
         │       Infraestrutura Local        │
         │  ┌─────────────────────────────┐  │
         │  │       Supabase Local        │  │◄── Autoridade Principal de Escrita
         │  │     (Banco de Operação)     │  │
         │  └─────────────────────────────┘  │
         └───────────────────────────────────┘

1. Supabase Local como Autoridade

Durante o funcionamento normal, todas as operações do dia a dia são executadas no Supabase Local. Não replicamos tabelas completas para a nuvem; em vez disso, a aplicação local gera snapshots operacionais consolidados que são publicados em background.

2. Supabase Cloud como Auth e Transporte

Auth Permanente: A autenticação centralizada permanece na nuvem. O application server valida a sessão do usuário contra o provedor central antes de liberar acessos e operações no nó local.
Projeção de Leitura e Fila: Em falhas do nó local, a nuvem fornece leituras de snapshots compactos e serve como fila temporária de transporte para novos comandos.

Estados de Operação e Circuit Breaker

O comportamento da aplicação é controlado por um Circuit Breaker que transiciona entre três estados com base na disponibilidade do primário local:

stateDiagram-v2
    [*] --> PRIMARY : Inicialização
    
    PRIMARY --> DEGRADED : Inacessibilidade do Primário Local
    DEGRADED --> RECOVERING : Primário Local Responde Novamente
    RECOVERING --> PRIMARY : Fila até high-water mark drenada + probes OK
    RECOVERING --> DEGRADED : Falha na reconciliação

1. Estado PRIMARY (Operação Normal)

O tráfego de leitura e escrita é direcionado ao Supabase Local.
O componente outbox do banco local publica snapshots consolidados para a nuvem de forma assíncrona.
A aplicação acessa o primário por uma API HTTPS protegida pelo Cloudflare Tunnel; a latência real precisa ser medida antes do rollout.

2. Estado DEGRADED (Falha do Nó Local)

Acionado quando o app server detecta a indisponibilidade do primário local (timeouts, falhas de conexão ou erros 5xx no banco local).
Nesse estado, não há gravação local.
O Circuit Breaker direciona todas as consultas de leitura para os snapshots compactos armazenados no Supabase Cloud.
A aplicação segmenta suas funções rigidamente:
- Operações Essenciais (Habilitadas): Ações como a criação de novos pedidos, pagamentos e atualização de status de entrega são aceitas pelo app server e enfileiradas diretamente no Supabase Cloud como comandos pendentes.
- Operações Desabilitadas: Recursos secundários como processamento de IA (recomendações), galeria de imagens completa sob demanda e uploads de arquivos grandes são desativados no frontend para conservar recursos.

3. Estado RECOVERING (Alinhamento de Fila)

O primário local volta a responder, mas o sistema permanece em modo de transição.
O Supabase Local consome sequencialmente os comandos pendentes acumulados no Cloud.
No desenho alvo, a transição final de volta para PRIMARY exige drenar até o high-water mark capturado na falha e confirmar probes de saúde. O núcleo já implementa os probes; o fencing global ainda é pré-requisito do rollout de escritas reais.

Idempotência sem Dois Escritores

A nuvem não cria registros de negócio concorrentes. Ela grava apenas um envelope de intenção com command_id e idempotency_key únicos. O banco atribui queue_sequence no INSERT para orientar a drenagem; occurred_at fica como metadado e não determina a ordem do claim.

O handler no primário também precisa registrar a chave de idempotência na mesma transação do efeito. Isso cobre inclusive o caso em que uma chamada dá timeout na borda, é enfileirada, mas termina com commit tardio no local.

Tratamento de Webhooks Fiscais e Pagamentos

Os webhooks de pagamentos (como retornos de confirmação de Pix ou cartões) chegam diretamente ao application server hospedado (e.g., Cloudflare Workers na nuvem).

Gateway de Pagamentos ──► App Server Cloud (CF Workers)
                                  │
                                  ▼
                         Journaling da Fila Cloud
                         (Garantia de Idempotência)
                                  │
                       [Supabase Local Online]
                                  │
                                  ▼
                         Worker Local faz Pull
                         e aplica a alteração no banco

Recepção: O Worker recebe o webhook na nuvem, valida a assinatura e realiza o journaling (gravação) do payload na fila de eventos do Supabase Cloud.
Idempotência: Uma chave de idempotência exclusiva por transação impede que webhooks repetidos criem comandos duplicados na fila.
Consumo: O nó local, ao restabelecer conectividade, realiza o pull assíncrono desses eventos da nuvem, processando-os localmente de maneira ordenada.

Testes de Caos: Simulando a Queda do Local

A resiliência da arquitetura é validada por testes de injeção de falhas que forçam o chaveamento de fluxo.

Teste de Fallback Cloud

O teste consiste em derrubar intencionalmente a infraestrutura do Supabase Local. O objetivo é comprovar que o tráfego de leitura de snapshots é redirecionado instantaneamente para o Supabase Cloud e que as escritas essenciais continuam sendo journaladas na nuvem como comandos pendentes, garantindo que a aplicação permaneça funcional para transações críticas mesmo sem o banco primário local.

Estado da Implementação e Próximas Fases

[!IMPORTANT] A implementação deve ser conduzida em fases rigorosas. Métricas reais de latência e consumo de banco devem ser coletadas no ambiente de testes sob carga simulada antes de homologar a solução para produção.

Visão Executiva: Perfil Local-Primary com Supabase