Arquitetura do Portal MBL

Visao Geral

Plataforma completa de gestao para nucleos do MBL. Suporta multi-tenant (cada nucleo e um tenant isolado) e multi-membership (um usuario pode ser membro de multiplos nucleos com cargo, saldo e plano independentes). Economia gamificada com moeda virtual (nome e sigla configuraveis por nucleo), integracao de pagamentos via Asaas, comunicacao interna, porta-vozes com sync automatico de redes sociais, e IA generativa.

Stack Tecnologica

Estrutura do Monorepo

mbles/
├── apps/
│   ├── web/              # Frontend Next.js 15 (45+ rotas)
│   │   ├── src/app/      # App Router (auth/, dashboard/)
│   │   ├── src/components/ # Componentes reutilizaveis
│   │   ├── src/hooks/    # Hooks (use-user com multi-membership)
│   │   └── src/lib/      # Utilitarios (supabase, nucleo, phone, api-fetch)
│   │
│   ├── api/              # Backend NestJS 10 (32 modulos)
│   │   ├── src/modules/  # 32 modulos (auth, membros, membership, economia, ...)
│   │   ├── src/common/   # Guards, Interceptors, Decorators
│   │   └── src/supabase/ # Supabase service (clients: service role, anon, per-user)
│   │
│   └── docs/             # Documentacao tecnica (este portal)
│
├── packages/
│   └── shared/           # Tipos e enums compartilhados entre web e api
│
├── supabase/
│   ├── migrations/       # 41 migrations PostgreSQL
│   └── email-templates/  # Templates HTML de email (recovery, signup, etc)
│
├── CLAUDE.md             # Instrucoes para copilots de IA (32 modulos documentados)
├── README.md             # Visao geral + setup local
└── CONTRIBUTING.md       # Git flow, commits, deploy

Multi-Tenant + Multi-Membership

O sistema e multi-tenant: cada nucleo (MBL-ES, MBL-SP, etc) e um tenant isolado com dados separados. Alem disso, suporta multi-membership: um mesmo usuario (mesmo email/CPF/senha) pode ser membro de multiplos nucleos simultaneamente, com cargo, status, saldo de moedas e plano independentes por nucleo.

Fluxo de Autenticacao

1. Browser faz signInWithPassword (Supabase Auth) → cookies SSR setados
2. Frontend chama POST /api/auth/login → retorna nucleos[] (memberships ativas)
3. Se 1 nucleo → entra direto
   Se N nucleos → /auth/selecionar-nucleo
   Se dominio nao-membro → botao "Solicitar acesso"
4. SUPER_ADMIN → entra direto, dropdown global de nucleos
5. Toda request API inclui header X-Tenant-ID com nucleo ativo
6. AuthGuard valida membership em membros_nucleos e injeta:
   - request.user.nucleoId
   - request.user.cargo (do nucleo ativo)
   - request.user.isConvidado
   - request.user.isNucleoOrigem

RBAC (Role-Based Access Control)

Cargo e por nucleo (via membros_nucleos.cargo). Um usuario pode ser COORDENADOR no ES e MEMBRO no SP.

Economia (Moeda Virtual)

Cada nucleo define nome_moeda e sigla_moeda (ex: "Capixacoins"/"CC"). O saldo e calculado via ledger (transacoes_moeda) e cacheado em membros_nucleos.saldo_capixacoins(atualizado por trigger PostgreSQL). Multiplicador global e teto mensal configuraveis por nucleo.

Integracao Asaas

• Config por nucleo: cada nucleo tem sua propria API key e ambiente (sandbox/production)
• Webhook: recebe eventos de pagamento (CONFIRMED, OVERDUE, REFUNDED) e atualiza pedidos/assinaturas
• Sync automatico: cron diario (3h) busca cobrancas confirmadas no Asaas e atribui planos + cria lancamentos financeiros
• Rebuild financeiro: trigger manual busca TUDO no Asaas, agrupa parcelas, filtra testes e futuros, cria lancamentos retroativos
• Split payment: compras podem ser pagas parte em moeda virtual + parte em R$ (PIX/cartao/boleto)

Porta-Vozes e RSS

• YouTube: sync automatico via RSSHub auto-hospedado (cron a cada 5h)
• Twitter/X: sync automatico via RSSHub + auth_token cookie
• Instagram: adicao manual (admin cola URL do post/reel, sistema gera embed). API oficial planejada para futuro.
• TikTok: suportado via RSSHub (quando disponivel)
• Postagens automaticamente aparecem no feed do nucleo e geram notificacoes

Deploy

Todo o deploy e feito via Google Cloud Run:

Banco, auth e storage ficam no Supabase Cloud (remoto). Nao ha Supabase local.