Manual do Mandir
Fonte canônica de verdade do sistema. Antes de planejar qualquer mudança, consulte aqui. Se algo no manual está desatualizado em relação ao código, o código vence, mas o manual deve ser corrigido na mesma sessão.
Audiência: Felipe + Antonio Mendes + qualquer IA (Claude, agentes futuros) + qualquer humano novo entrando no sistema.
Princípio: documentar o que existe, não o que se planeja. Itens em fluxo ficam marcados como tal.
Como o manual está organizado
Cada módulo do Mandir Suite tem um arquivo dedicado em manual/<modulo>.md. O arquivo cobre:
- Identidade — o que faz, por que existe (negócio + técnico), quando entrou em prod, status atual.
- Cases de uso reais — como Mais Consciente (e clientes) usam hoje.
- Oportunidades de negócio — o que esse módulo poderia virar / vendas externas / extensões naturais.
- Arquitetura interna — services, models, tasks Celery, adapters externos, fluxos.
- Tabelas + relacionamentos — schema completo, FKs cross-módulo (sempre via service, nunca FK física), índices relevantes.
- API/Endpoints — método + rota + payload + retorno + autenticação + autorização.
- Eventos emitidos/consumidos — integração via
mandir-events(cross-módulo desacoplado). - Configuração — env vars,
settings_identity, feature flags, kill switches. - Operações — como ligar/desligar, troubleshooting, runbooks vinculados.
- Métricas + observabilidade — logs estruturados-chave, dashboards, alertas.
- Limitações + débitos técnicos conhecidos — gotchas, workarounds, próximos passos planejados.
- Histórico relevante — migrations principais, commits que cravaram funcionalidade, ADRs.
Ver _TEMPLATE.md para o esqueleto canônico que todo módulo segue.
Status dos módulos
Convenção:
- 🟢 Estável — em produção, contrato cravado, mudança só com aviso explícito
- 🟡 Em fluxo — em produção mas sob iteração frequente
- 🔵 MVP — primeira versão entregue, em uso restrito ou validação
- ⚪ Esqueleto — existe no código mas sem uso real ainda
- 🔴 Quebrado / dívida ativa — funciona parcialmente, débito conhecido bloqueia uso
Por domínio de negócio
Comunicação (canais com humano final)
| Módulo | Status | Doc | Resumo |
|---|---|---|---|
| 🟢 | ✅ | Inbox WhatsApp via Evolution + Meta Cloud, threads, templates, campanhas, automações, RLS por tenant | |
| 🟢 | ✅ | DMs (Hub.7) + Comments (Hub.8) + Insights (Hub.5), token cifrado | |
| 🟡 | ✅ | Brevo + Resend + SendGrid, sequências, journeys, A/B, signup forms | |
| chat | 🔴 | ✅ | Em manutenção — quebrou recentemente, dívida ativa |
| forms | 🔵 | ✅ | Formulários públicos com submissão; sem tools no Conselho ainda |
Inteligência (centro do produto)
| Módulo | Status | Doc | Resumo |
|---|---|---|---|
| council | 🟢 | ✅ | Conselho IA (8 conselheiros), pipeline assíncrono, mirror, digests, kill switch separado dos agentes |
| agents | 🟡 | ✅ | Agentes externos (Hari, Clara, Aurora, Chandra, Dunning) — modo rascunho (auto_respond=false) |
| intelligence | 🟢 | ✅ | L1 contact_attribute, L3 patterns, L5 brain_observation — Sprint 1.B/1.C/2.A do Brain |
| business | 🟢 | ✅ | Knowledge, products, price_inquiries, objections, appointments, brain_config |
Relacionamento + clientes
| Módulo | Status | Doc | Resumo |
|---|---|---|---|
| crm | 🟢 | ✅ | Contacts, deals, tags, scoring, custom fields, accounts (B2B), notifications, webhooks |
| members | 🟢 | ✅ | Members + programs + enrollments — gate de acesso restrito |
| community | 🟡 | ✅ | 34 endpoints — feed, posts, reações, moderação |
| meetings | 🟢 | ✅ | Aulas ao vivo via Daily.co + gravação Bunny CDN, attendance, recordings |
Marketing + atribuição
| Módulo | Status | Doc | Resumo |
|---|---|---|---|
| marketing | 🟢 | ✅ | Hub.1 framework + Hub.2 Meta Ads + Hub.4 Google Ads (paid only) |
| analytics (GA4) | 🟢 | ✅ | Hub.3 GA4 — tabelas L0 + tools Council |
| youtube | 🟢 | ✅ | Hub.6 YouTube channel insights |
| attribution | 🟢 | ✅ | Campaign + touchpoint + UTM resolution + bridge organic IG/YT |
| tracking | 🟡 | ✅ | Eventos, integração com mandir-events |
| links | 🟡 | ✅ | Link shortener + capture + click tracking + custom domains |
Produtos (cursos / surveys / NR-01)
| Módulo | Status | Doc | Resumo |
|---|---|---|---|
| programs | 🟢 | ✅ | Programs, periods, modules, lessons, cohorts, journeys, guides, acervo |
| surveys | 🔵 | ✅ | Forms + submissions + dimension scores + retention policies |
| nr01 | 🔵 | ✅ | NR-01 modular, módulo privado Mais Consciente — Colorado é primeiro projeto |
| diary | 🟢 | ✅ | Diary entries, prompts, devolutivas — escopo restritíssimo |
Plataforma + operações
| Módulo | Status | Doc | Resumo |
|---|---|---|---|
| auth | 🟢 | ✅ | Login, me, setup-password — frontal pro identity service |
| billing | 🟢 | ✅ | Asaas multi-tenant, credenciais cifradas, approval workflow |
| platform_admin | 🟢 | ✅ | Provisioning, drop scheduler, dunning, billing approvals — cross-DB |
| settings | 🟢 | ✅ | Identity, branding, pixel, compliance, domain, legal_entity |
| staff | 🟡 | ✅ | Equipe interna do tenant |
| connections | 🟡 | ✅ | Integrações OAuth (Google, Meta, etc.) — base pros Hubs |
| help | 🟡 | ✅ | Help articles + feature requests |
| design | 🟡 | ✅ | Templates de design + design system |
| health | 🟢 | ✅ | Health checks |
Por contagem
- 30 módulos no backend
- 243 tabelas no schema
- 1 mega-módulo (whatsapp, 81 .py files, 34 tabelas)
- 5 módulos grandes (council, marketing, email, crm, programs)
Como atualizar o manual
Regra: toda mudança de comportamento de um módulo (novo endpoint, nova tabela, nova task Celery, mudança de contrato, kill switch novo) deve atualizar o doc do módulo na mesma sessão. Se a mudança é grande, criar entrada no ## Histórico relevante do doc com data + commit.
Quando criar doc novo: módulo novo entra com doc no momento que vai pra prod. Se está em rascunho, ainda não precisa.
Quando reescrever doc: se um refactor mudou >30% das tabelas/endpoints do módulo, preferir reescrever do zero a remendar.
Quem mantém: quem fez a mudança. Se foi IA, IA atualiza no mesmo turno. Se foi Felipe ou Antonio, atualizar no PR.
Como consultar o manual
Antes de implementar qualquer feature nova: ler o doc do módulo afetado + módulos vizinhos (dependências).
Para help no app: o frontend pode renderizar esses MDs em /admin/manual (rota planejada — fase 2 deste manual).
Para outras IAs: apontar pra esses arquivos antes da query (RAG ou contexto direto).
Convenções
- pt-BR em todo conteúdo (consistente com CLAUDE.md global)
- Sem emoji em texto corrido (apenas em status: 🟢🟡🔵⚪🔴)
- Sem Sânscrito em nomes de módulo, função, tabela, conceito
- Tabelas Markdown sempre que comparar coisas; prosa pra explicar
- Linkar memórias quando relevante:
[[nome-da-memoria]]no estilo Obsidian - Citar arquivos com path clicável
Histórico do manual
- 2026-05-13 — Manual criado. Substitui o
funcoes-crm-2026-05-02.mdlegacy do Tantu (CRM Saraswati). Estrutura por módulo + função-por-função, multi-domínio. Pilotos iniciais: council + whatsapp.
Quando em dúvida, leia o código. Quando o código surpreender, atualize este manual.