ADR-001: Local-First como estratégia de disponibilidade
| Campo | Valor |
|---|---|
| Status | Aceito |
| Data | 2024 |
| Autor | Caio Fiori Martins |
Contexto
O Ouroboros opera em feiras e eventos escolares. Esses ambientes têm características específicas que diferem radicalmente de uma aplicação web convencional:
- Rede WiFi sobrecarregada com dezenas ou centenas de dispositivos simultâneos
- Conexão com internet instável ou inexistente dependendo da infraestrutura da escola
- Operação em janelas de tempo curtas e críticas — um evento de 4 horas não tem tolerância a downtime
- Sem equipe de suporte técnico — a organização do evento não é uma empresa de tecnologia
- Consequências reais de falha — um terminal que para de funcionar paralisa a loja
A alternativa mais óbvia — hospedar tudo em nuvem (Firebase, Supabase, etc.) — foi avaliada e apresenta riscos inaceitáveis nesse contexto.
Problema com cloud-first nesse contexto
Uma arquitetura onde cada transação depende de uma chamada de rede externa está exposta a:
1. Rate limiting
Firebase Firestore no plano gratuito limita writes por segundo. Um evento com múltiplas lojas simultâneas pode facilmente atingir esse limite durante os picos. Quando isso acontece, as requisições são bloqueadas — não degradadas, bloqueadas.
2. Latência de rede
Uma requisição que deveria completar em < 50ms passa a depender da latência até o servidor do Firebase (tipicamente 100–400ms em conexões residenciais brasileiras). Em WiFi congestionado, pode ser muito mais.
3. Falha total
Se a internet cai — e em ambientes escolares isso é completamente plausível — o sistema para. Completamente. Todas as lojas param.
4. Complexidade de fallback
Implementar um fallback offline decente para cloud-first é mais complexo do que simplesmente começar local-first. Você acaba construindo um sistema local de qualquer forma, mas como workaround mal especificado.
Decisão
O servidor principal e o banco de dados rodam na rede local do evento.
Toda operação crítica (criar comanda, debitar, creditar, consultar saldo) é processada localmente, sem dependência de internet. A nuvem existe como camada de conveniência — não de infraestrutura.
Alternativas consideradas
Alternativa A: Firebase como banco principal
Cada transação vai diretamente pro Firestore. Simples de implementar.
Descartada por: rate limiting, latência, falha total em caso de queda de internet.
Alternativa B: Servidor cloud dedicado (VPS)
Servidor próprio em nuvem (DigitalOcean, etc.) como backend.
Descartada por: mesmos problemas de dependência de internet + custo + complexidade de operação desnecessária para o escopo.
Alternativa C: Híbrido com sync eventual (escolhida)
Servidor local como fonte da verdade. Firebase como espelho eventual para consulta do cliente.
Escolhida por: elimina todos os riscos de disponibilidade mantendo a conveniência de consulta mobile.
Consequências
Positivas:
- Disponibilidade praticamente garantida durante o evento
- Latência de transação < 50ms (loopback na rede local)
- Sem custo de infraestrutura para o caso de uso principal
- Funciona mesmo sem internet
Negativas e trade-offs aceitos:
- Requer que um dispositivo rode o servidor durante todo o evento (custo operacional baixo)
- O cliente pode ver saldo desatualizado no celular caso a sync com Firebase esteja atrasada — documentado e esperado (eventual consistency)
- Setup inicial levemente mais complexo do que "abrir o Firebase e sair usando"
Notas
A decisão de usar local-first não é nova — é o padrão adotado por sistemas de PDV (ponto de venda) comerciais exatamente pelo mesmo motivo: um supermercado não pode parar de vender porque a internet caiu. Ouroboros aplica o mesmo raciocínio a um contexto escolar.