Visão geral da arquitetura

Limites de responsabilidade

flowchart TB
    subgraph Presentation[Apps Flutter]
      UI[Pages e widgets] --> State[BLoC e Cubit]
    end
    State --> UC[Casos de uso]
    UC --> Ports[Interfaces de repository]
    Ports --> Adapters[aivaleu_data]
    Adapters --> Auth[Firebase Auth]
    Adapters --> DB[(Cloud Firestore)]
    Adapters --> Fn[Callable Functions]
    Adapters --> Store[Firebase Storage]
    Fn --> DB
    Fn --> Stripe[Stripe API]

aivaleu_domain não depende de Flutter nem de Firebase. Ele publica entidades, enums, casos de uso e portas. aivaleu_data adapta essas portas para os SDKs Firebase. Cada app registra implementações em get_it e expõe repositories aos Cubits/BLoCs.

Processos executáveis

Processo	Entrada	Composição	Efeito principal
App cliente/parceiro	apps/aivaleu_app/lib/main.dart	initDI() + providers	Auth, feed, ofertas, cupons, carteira, campanhas e gestão do parceiro
Garçom	apps/waiter_desktop/lib/main.dart	initInjection()	Sessão anônima limitada, login do garçom e confirmação de check-in
Curadoria	apps/super_admin_web/lib/main.dart	initDI() + GoRouter	Operações protegidas pelo claim super_admin
Backend	functions/index.js	exports de functions/src/*	Callables, HTTP webhook, gatilhos Firestore e schedulers

Todas as Functions exportadas usam southamerica-east1. O webhook Stripe é HTTP; as operações dos apps usam callables autenticadas. O backend inicializa firebase-admin uma única vez em functions/index.js.

Onde cada regra vive

Regra	Autoridade
Estrutura e decisões locais de UI	Pages, Cubits e casos de uso Dart
Autorização de leitura/escrita direta	firestore.rules e storage.rules
Curadoria, autoria e deleção de oferta	Cloud Functions de oferta
Reserva e conversão do limite de cupons	Transações em coupons_functions.js e coupon_usage_limit.js
Sessão e confirmação do garçom	waiter_auth.js e confirm_checkin.js
Status temporal de campanhas/cupons	Schedulers e documento settings/schedulers
Premium cobrado	Stripe + webhook + documentos subscriptions/users
Elegibilidade Premium apresentada no app	Entidades/use cases, sempre revalidada no backend ao gerar cupom

Consistência e concorrência

• Geração, cancelamento, expiração e uso de cupom atualizam cupom e contadores da oferta em transações Firestore.
• couponUsageLimit = null representa uma oferta sem limite. Em ofertas limitadas, couponReservedCount + couponUsedCount não pode superar o limite.
• O login do garçom cria waiter_sessions; confirmCheckin verifica sessão ativa, expiração, garçom e unidade na mesma operação de leitura/transação.
• Eventos Stripe usam stripeEvents como marcador de idempotência.
• Schedulers são implantados a cada minuto, mas scheduler_runner.js aplica enabled, intervalo permitido e lastRunAt do documento settings/schedulers.

Falhas e observabilidade

As Functions callables normalizam falhas em códigos HttpsError, principalmente unauthenticated, permission-denied, invalid-argument, not-found, already-exists, resource-exhausted, failed-precondition e internal. Os apps traduzem parte dessas falhas em estados de Cubit/BLoC; os logs operacionais saem por console.*, debugPrint e AppLogger.

Não há, no repositório, configuração versionada de alertas, tracing distribuído ou dashboards externos. Logs locais e Firebase Functions Logs são os mecanismos comprovados.