Arquitetura do Portal Meu Núcleo - MBL

Visao Geral

O Portal Meu Núcleo - MBL e uma plataforma web para gestao de militancia, com economia interna gamificada (moeda virtual do nucleo, nome e sigla configuraveis, ex: Capixacoins/CC), eventos, projetos, loja e sistema de pagamentos real (Asaas).

Stack Tecnologica

Estrutura do Monorepo

mbles/
├── apps/
│   ├── web/          # Next.js frontend (Google Cloud Run)
│   ├── api/          # NestJS backend (Cloud Run)
│   ├── docs/         # Este portal de documentacao
│   └── mobile/       # Capacitor (Android/iOS)
├── packages/
│   └── shared/       # Types, enums, Zod schemas
├── supabase/
│   ├── migrations/   # SQL migrations
│   └── seed.sql      # Dados iniciais
├── .github/workflows/  # CI/CD
├── turbo.json        # Turborepo config
└── CLAUDE.md         # Convencoes do projeto

Fluxo de Dados

Browser/App
    │
    ├──► Next.js (Google Cloud Run) ──► Supabase Auth (login/signup)
    │                     ──► Supabase DB (via RLS, leitura direta)
    │
    └──► NestJS API (Cloud Run)
              │
              ├──► Supabase DB (service_role, bypassa RLS)
              ├──► Supabase Storage (uploads)
              ├──► Asaas API (pagamentos)
              ├──► OpenAI API (IA — resumos, chat, matching)
              └──► Resend API (emails transacionais)

Fluxo de Autenticacao

1. Frontend faz login via Supabase Auth (email/senha)
2. Supabase retorna JWT (access_token + refresh_token)
3. Frontend envia JWT no header Authorization: Bearer token para o NestJS
4. NestJS valida o JWT com Supabase e extrai user_id + nucleo_id
5. Middleware de tenant garante isolamento multi-tenant

Multi-tenancy

Todas as tabelas (exceto nucleos e planos) possuem a colunanucleo_id. O backend injeta automaticamente o nucleo_id do usuario logado em todas as queries via TenantInterceptor.

No banco, Row Level Security (RLS) garante que mesmo queries diretas do frontend (via Supabase client) respeitam o isolamento de dados entre nucleos.

Pagamentos (Asaas)

Integrado desde o V1. Membros podem pagar com moeda do nucleo, reais (R$ via Asaas) ou um mix de ambos (split payment). O Asaas suporta PIX, Cartao de Credito, Debito e Boleto.

Mobile

O app mobile usa Capacitor para empacotar o Next.js como app nativo. Uma unica codebase responsiva serve desktop (browser) e mobile (Google Play / App Store). Push notifications via Firebase Cloud Messaging.

Modulos do Backend (NestJS)

Principais modulos do backend alem dos modulos base (Auth, Membros, Projetos, Eventos, etc.):

• NacionalModule: Modulo para funcionalidades de nivel nacional (produtos, comunicados, enquetes, emails). Acessivel apenas por Super Admin.
• SuperAdminReportsModule: Relatorios globais consolidados de todos os nucleos (7 abas: membros, economia, eventos, projetos, engajamento, planos, comparativo).
• IAToolsService: Servico que expoe ferramentas de IA para o chat (consultas ao banco, acoes de escrita, geracoes de texto). Utiliza OpenAI function calling.

Pacotes e Bibliotecas Adicionais