Kodama Hub — Master Plan

Tese comercial: Kodama vende SEMPRE o mesmo produto — o Hub. O que muda por cliente é o conjunto de módulos (ferramentas on-demand) ativados. Um core, N módulos, 1 fonte de verdade.

Status (2026-07-04) — F1-F6 implementadas em código, faltando deploy

Todas as 11 issues do backlog inicial (#21-#31) foram implementadas, auditadas (kodama-hub-auditor, todas APPROVED após fix rounds) e mergeadas em master no repo local. Ainda não deployadas em prod (hub.kodama.solutions) — tudo rodou contra dev local (docker-compose.dev.yml).

Wave	Commit	Conteúdo
1 — Fundação	2c9d154	store_features entitlements, contacts SSoT (upsert nos webhooks Meta+Evolution), sidebar modular + /upgrade/[module], /admin/modules
2 — Catálogo/CRM/Templates	8c30404	products CRUD + /c/[storeId] público, CRM kanban+tags, gestão de templates Meta (create/submit/status webhook)
3 — Pedidos/Campanhas/Automações	75746fc	orders v1, motor de envio segmentado (opt-out, daily cap, erro 131049), automações v1 (new_contact/tag_added/stage_changed)
4 — MCP + Chat IA	cc38981	8 tools MCP, endpoint externo /api/mcp (SDK oficial, Bearer API key), chat IA no painel (⌘J, loop agêntico via DeepSeek)

Ver plano original abaixo (§1-§7) — mantido como referência da visão. O que muda a partir daqui é execução, não arquitetura.

O que falta (não é dívida técnica pontual, é escopo real)

Deploy — nada disso está em prod ainda. Falta: aplicar migrations 0002-0006 no Postgres de prod, configurar OPENAI_API_KEY/OPENAI_BASE_URL (DeepSeek) no ambiente de prod pro chat funcionar, número real da Kodama em KODAMA_SALES_WHATSAPP (web/src/lib/modules.ts, hoje placeholder).

Automações — no_reply_24h não implementado (precisa scheduler/cron, MVP não tem). notify_owner é no-op (só loga, sem infra de notificação real).

Campanhas — send_message de automação usa texto livre (preso à janela de 24h do WhatsApp), não template — só campanhas manuais usam template aprovado.

MCP — v1 tem 8 tools (contatos, conversas, send_message, produtos, tag/stage, sales summary). Não cobre orders nem campaigns ainda (create_order, send_campaign não existem como tool).

Cobertura de teste — e2e/smoke.spec.ts não ganhou cobertura Playwright pras rotas novas (products/catalog/crm/campaigns/automations/chat) — QA foi via agent-browser nos audits, não é regressão automatizada.

Bugs pré-existentes, não desta iniciativa, resurfaced em 3 audits diferentes — vale priorizar por estarem no golden path real: /onboarding/billing 404 depois de registrar empresa (rota não existe); hydration warning em /stores (HeaderUserProfile, SSR vs client diverge).

Decisões de negócio ainda abertas (§7, inalterado): preço, checkout online no catálogo, domínio próprio por cliente, Meta Tech Provider (só necessário quando onboarding manual virar gargalo de escala).

---

1. Visão

Plataforma central onde o cliente da Kodama:

• Cadastra produtos e vende via catálogo online público
• Compra ferramentas on-demand (CRM, Campanhas, Automações, Agentes…) — Kodama libera no painel
• Tem todos os clientes dele conectados — single source of truth (contato que chega pelo WhatsApp = mesmo contato no CRM = mesmo comprador do catálogo)
• Opera tudo via chat IA embutido, executando ações reais através do MCP kodama-hub

Diagrama de referência: CRM · Cardápios/Catálogos · Agentes/BOT · Automações · Campanhas · Controle chat IA — todos orbitando o KODAMA HUB.

2. O que já existe (assets reaproveitáveis)

Asset	Estado	Vira
kodama-hub atual	Multi-tenant (stores/agents), canal Meta+Evolution por número, webhook+roteamento, RAG (DeepSeek+pgvector), docs+scrape, painel admin, E2E, auditores	Core + módulo Agentes/BOT (pronto ~90%, falta launch-QA)
vek1 (projeto irmão)	E-commerce completo: products, catalog, orders (~120 arquivos podados do fork)	Módulo Catálogo (re-port, não reescrever)
lunacrm	CRM multi-tenant SaaS rodando no VPS	Referência/porta pro módulo CRM
Infra Hermes	Docker + nginx + Postgres/pgvector + Ollama + backup pg_dump diário	Deploy de tudo

3. Arquitetura modular

3.1 Entitlements (fundação de TUDO)

Tabela store_features: store_id, feature_key ('agents' | 'catalog' | 'crm' | 'campaigns' | 'automations' | 'ai_chat'), enabled, activated_at, expires_at, metadata.

• Gate na UI: sidebar renderiza só módulos ativos; módulo inativo aparece como card "Disponível — fale com a Kodama" (upsell embutido)
• Gate no server: guard por rota/action — feature off = 403. Nunca só esconder botão.
• Admin Kodama (interno): toggle por tenant. Billing manual no início (pagou → liga).

3.2 Core (todo cliente tem, não é módulo)

• Auth multi-tenant (Better Auth, já existe)
• Empresa (store) + Números (agents) + canal Meta/Evolution (já existe)
• Contacts — a fonte de verdade. Todo mundo que manda mensagem vira contato automaticamente (phone como chave natural). Módulos leem/escrevem no mesmo registro: CRM adiciona pipeline+tags, Catálogo adiciona pedidos, Campanhas adiciona segmentos.
• Inbox de mensagens (já existe a base via webhook)

3.3 Módulos

Agentes/BOT (existe hoje) — RAG por número, persona, base de conhecimento. Primeiro módulo vendável.

Catálogo — products CRUD + página pública hub.kodama.solutions/c/<slug> (ou domínio próprio depois). Pedido fecha via WhatsApp (click-to-chat pro número do tenant — sinergia direta com módulo Agentes: bot recebe o pedido). Checkout online = fase 2 do módulo (AbacatePay). Fonte: re-port do vek1.

CRM — contatos (do core) + pipeline kanban, tags, notas, histórico de conversa anexado ao contato. O diferencial: CRM já nasce populado pelas conversas do WhatsApp — zero data entry. Referência: lunacrm.

Campanhas — disparo segmentado (por tag/pipeline do CRM) via canal do número. Cloud API = template messages aprovados (caminho seguro); Evolution = mensagem livre com rate limit agressivo + warmup (risco de ban — ver §6).

Automações — regras trigger→ação: "novo contato → tag X", "pedido criado → mensagem Y", "sem resposta 24h → notifica dono". Começa como lista de regras predefinidas configuráveis, NÃO builder visual (escopo controlado). Builder visual só se demanda provar.

Controle Chat IA + MCP (a cola de tudo):

• MCP server kodama-hub expondo tools escopados por tenant: list_contacts, search_conversations, create_product, update_product, send_message, move_deal, tag_contact, create_campaign, get_sales_summary…
• Tools respeitam entitlements (sem módulo CRM → sem tools de CRM)
• Chat embutido no painel consome o MCP — cliente digita "cria produto X por R$50 e manda o link pro João" e acontece
• Auth: API key por tenant; MCP também utilizável externamente (cliente pluga o Claude dele no hub) — diferencial de venda forte
• Implementação: FastAPI já existe → MCP server Python (SDK oficial) no mesmo deploy, ou endpoint HTTP+SSE

4. Roadmap

F0 — Fechar MVP atual (agora): rodar kodama-hub-launch-qa, resolver blockers, primeiro cliente real no módulo Agentes. Nada de módulo novo antes disso.

F1 — Fundação modular (pequena, destrava tudo): store_features + guards server + sidebar dinâmica + cards de upsell + toggle no admin.

F2 — Catálogo: re-port do vek1 (products, página pública, click-to-chat). Maior alavancagem: código existe, vende fácil, sinergia com bot.

F3 — CRM lite: contatos auto-populados + kanban + tags + timeline de conversas.

F4 — Chat IA + MCP: agora tem superfície (agentes+catálogo+CRM) pras tools operarem. MCP server + chat no painel.

F5 — Campanhas: segmentação por tags (depende do CRM) + templates Cloud API + rate limit Evolution.

F6 — Automações: triggers dos módulos anteriores.

Contínuo: billing manual → AbacatePay/Stripe self-service quando volume justificar.

Racional da ordem: F1 antes de qualquer módulo (senão vira monolito de novo). Catálogo antes de CRM (código pronto no vek1 > port do lunacrm). MCP depois de 3 módulos existirem (tools precisam de domínio pra agir). Campanhas depois do CRM (segmentação precisa de tags).

5. Modelo comercial (proposta inicial)

• Base (core + 1 número + Agentes/BOT): mensalidade fixa
• Módulo adicional: + valor/mês cada
• Número adicional: + valor/mês
• Onboarding manual pela Kodama (white-glove) — é feature, não bug: justifica preço agência
• Preços concretos: decisão do Marcus (ver §7)

6. Riscos

Risco	Mitigação
Ban WhatsApp por campanha em massa via Evolution	Rate limit forte, warmup, opt-out, empurrar Cloud API templates pra volume
Escopo infinito (6 módulos, 1 dev)	Fases estritas; módulo só entra quando cliente pagante pedir
Re-port vek1 diverge do hub atual	Port cirúrgico por feature, auditor roda a cada etapa
MCP com escrita = superfície de dano (IA deleta produto)	Tools de escrita com confirmação; audit log por tool call; escopo por API key
Single source of truth quebra se módulo criar contato próprio	Regra dura: contacts é do core, módulo NUNCA cria tabela paralela de pessoa

7. Decisões abertas (Marcus)

1. Preço da base e dos módulos
2. Catálogo: só pedido-via-WhatsApp no início (recomendado) ou checkout online já na F2?
3. CRM: port do lunacrm ou build novo em cima do schema do hub? (recomendado: build novo, lunacrm só de referência de UX — schema do hub já tem contacts/messages)
4. Domínio próprio por cliente no catálogo (catalogo.cliente.com.br) — F2 ou depois?

---

Relacionado: projects/kodama-hub/index · projects/kodama-hub/launch-qa-checklist · projects/vek1/index · projects/lunacrm/index