☁️ Rode este CRM em produção com 1 comando

O DeskcommCRM foi desenvolvido em parceria com a HostGator: o hostgator-setup-kit/
instala o CRM completo (app + WAHA + banco) numa VPS com um único comando, e o
runbook de produção já assume esse ambiente.

👉 Assinar a VPS HostGator com desconto da parceria —
datacenter em São Paulo, ideal pro WhatsApp rodando 24/7. (link de parceiro — assinar por ele apoia o projeto e sai mais barato)

✨ O que é

DeskcommCRM unifica atendimento humano, agentes de IA com RAG por tenant, gestão de pedidos e pipeline de pós-venda numa única plataforma. Canal primário: WhatsApp via WAHA. Multi-tenant desde o dia 1. LGPD nativa.

Modo atual: BPO interno (uma operadora atende N tenants).
Modo futuro: SaaS direto pra lojistas.

Diferenciais

• 🤖 IA operando o atendimento — agentes com RAG por tenant, análise de sentimento, handoff IA→humano auditado e controle de budget. Não é chatbot decorativo, é triagem real.
• 🛒 E-commerce-native — vocabulário desenhado pro ciclo Carrinho abandonado → Pago → Enviado → Entregue → Pós-venda.
• 🇧🇷 LGPD by-design — webhooks customer/redact e customer/data_request da Nuvemshop como contrato de primeira-classe; anonimização preferida sobre delete; audit append-only com retenção 5 anos.
• 👥 Governança de atendimento — RBAC server-side de verdade, atribuição/transferência auditada, fila com posição, roteamento automático e escopo de visualização por papel.
• 🔌 MCP-ready — MCP server interno pros agentes; contrato público pra agentes externos em construção.
• 🏢 Multi-tenant de verdade — RLS em toda tabela tenant-aware, teste de isolamento como gate de CI.

🔌 Webhooks & Automações

Todo tenant pode criar fontes de captação: um endereço público (/api/v1/webhooks/in/<token>) que recebe leads de landing pages, formulários próprios ou ferramentas como Zapier/n8n via POST (JSON ou application/x-www-form-urlencoded) e já entra direto no funil/estágio escolhido — sem código, sem integração customizada por tenant. Em cima dessas fontes (e dos outros eventos do CRM — lead mudou de etapa, ganhou tag, chegou mensagem no WhatsApp), o tenant monta automações: regras no formato QUANDO/SE/ENTÃO que disparam ações como adicionar tag, mover o lead no funil, atribuir a um atendente, mandar uma mensagem de WhatsApp ou avisar outro sistema via webhook de saída.

Na UI, tudo mora em Webhooks na sidebar (visível só pra quem tem papel manager/admin — agent/viewer não veem o item nem acessam a rota, redirecionados pro inbox). A tela tem três abas: Receber dados (criar fonte, copiar o endereço/formulário pronto, disparar um lead de teste, ver os últimos recebimentos), Automações (montar a regra, que sempre nasce pausada até o tenant revisar e ligar) e Atividade (timeline de cada execução, com o resultado de cada ação e reenvio manual quando uma chamada de webhook externo falha).

Por baixo, cada evento (lead criado, tag adicionada, etc.) vira uma linha em event_log — nenhum trigger de banco faz chamada HTTP diretamente. Quem drena essa fila e realmente dispara as automações é a rota /api/v1/cron/event-log-drain, chamada a cada minuto. No Vercel isso é um Cron Job gerenciado; no kit self-host da HostGator (hostgator-setup-kit/), o install.sh/update.sh já configura sozinho uma linha de crontab que roda essa rota todo minuto com o INTERNAL_SECRET do .env — sem esse cron ativo, fontes e automações continuam sendo criadas normalmente, mas os eventos ficam empilhados em event_log e nenhuma automação chega a rodar de verdade.

🚀 Quickstart (5 minutos pra ver rodando)

# 1. Clone
git clone https://github.com/melgarafael/DeskcommCRM.git
cd DeskcommCRM

# 2. Node 20 + pnpm
nvm use                    # ou instale Node 20+
npm install -g pnpm
pnpm install

# 3. Env vars
cp .env.example .env.local
# Edite .env.local — guia completo em docs/SETUP.md

# 4. WAHA local (opcional em dev sem WhatsApp)
docker compose up -d

# 5. Migrations Supabase
supabase link --project-ref <seu-ref>
supabase db push

# 6. Sobe o app
pnpm dev

App: http://localhost:3000 · Health check: http://localhost:3000/api/v1/health

🆕 Primeira vez? Não pula etapa. docs/SETUP.md é o tutorial completo passo a passo de todas as integrações (Supabase, WAHA, Anthropic, Upstash, Sentry, Resend, Nuvemshop) — feito pra quem nunca configurou nada disso antes. ~60–90 min do zero ao app rodando.

🧱 Stack

Detalhes: ARCHITECTURE.md.

📁 Estrutura

DeskcommCRM/
├── app/                    # Next.js App Router
│   ├── (admin)/            # Rotas super-admin (impersonate, tenants)
│   ├── (public)/           # Login, recovery
│   ├── app/                # Rotas autenticadas: inbox, kanban, contacts,
│   │                       #   connections, ai (agentes), integrations,
│   │                       #   metrics, lgpd, audit, team, settings
│   └── api/v1/             # API REST canônica
├── components/             # React (ui/, inbox/, kanban/, shell/, ...)
├── lib/                    # supabase/, waha/, ai/, api/, routing/, env.ts
├── hooks/
├── supabase/migrations/    # SQL versionado (+ baseline.sql pro self-host)
├── workers/                # consumers de event_log (IA, RAG, LGPD, rotinas)
├── tests/{e2e,unit,invariants}/
├── scripts/                # seeds, qa-waves, manutenção
├── docs/                   # PRDs, specs, stories, SETUP.md
└── hostgator-setup-kit/    # instalação self-host com 1 comando

🧪 Testes

pnpm typecheck     # tsc --noEmit (estrito)
pnpm lint          # eslint next/core-web-vitals
pnpm test:unit     # Vitest
pnpm test:e2e      # Playwright (requer dev server)

CI roda todos antes de merge. Teste de isolamento RLS é gate obrigatório — cria 2 tenants e verifica não-vazamento. A suíte de invariantes de governança (100+ testes) trava regressões de RBAC, atribuição, escopo e roteamento.

📚 Documentação

🤝 Contribuindo

Esse projeto é open source pra comunidade. Toda contribuição é bem-vinda — desde fix de typo em doc até feature nova.

Antes de abrir PR:

1. Leia CLAUDE.md (~5 min) — convenções não-negociáveis (multi-tenancy, RLS, audit, LGPD).
2. Leia CONTRIBUTING.md — fluxo de branches, commits, epic-executor.
3. Siga o Código de Conduta.

Fluxo curto:

git checkout -b feat/short-slug
# implementa + testes
pnpm typecheck && pnpm lint && pnpm test:unit
git commit -m "feat(escopo): descrição"
# abre PR — o template já traz o checklist de Definition of Done

Definition of Done: typecheck zero, lint zero, testes relevantes verdes, RLS testada se toca tabela tenant-aware, audit log emitido em mutações, migration versionada se muda schema. Detalhes em CLAUDE.md.

🐛 Reportando bugs

Abra uma issue — o template pede o que precisamos (ambiente, /api/v1/health, steps).

Pra vulnerabilidades de segurança, NÃO abra issue pública — use o relato privado de vulnerabilidades. Detalhes em SECURITY.md.

🗺️ Roadmap

✅ Entregue

• Fundação & plataforma — auth (MFA pra admin), multi-tenancy com RLS + teste de isolamento, RBAC 4 papéis, audit log append-only, onboarding de tenant.
• Atendimento WhatsApp — inbox 3 painéis em tempo real, conexões WAHA multi-número, mídia via Storage, anti-banimento (throttle + jitter + janela de horário), STOP detection.
• CRM & pedidos — kanban com vocabulário e-commerce (fractional indexing), customer 360, contatos, tags, integração Nuvemshop.
• IA nativa — agentes com RAG por tenant (pgvector), análise de sentimento, handoff IA→humano, controle de budget por org, MCP server interno.
• LGPD — export e redact via workers, anonimização em cascata, consentimento auditado.
• Self-host — hostgator-setup-kit (app + WAHA + banco com 1 comando), baseline.sql auto-curativo, runbook de produção.
• Webhooks & automação — gatilhos de eventos do CRM pra sistemas externos.

🔄 Em andamento — Governança de Atendimento

Épico guiado por invariantes (suíte de 100+ testes como eval), fase a fase:

• ✅ G1 — provas & fundação (invariantes dos 7 eixos de dor, CI consolidado)
• ✅ G2 — RBAC server-side em toda a API (matriz papel×endpoint)
• ✅ G3 — atribuição & transferência auditadas; IA como assignee de 1ª classe; tags
• ✅ G4 — escopo de visualização por papel (RLS) + métricas por atendente
• 🔄 G5 — roteamento automático, fila com posição e painel de gestão (fechando)
• 🔜 G6 — contrato de governança pra agentes de IA externos (MCP tools públicas)

🔮 Próximo

• MCP público — capabilities do CRM expostas pro ecossistema de agentes.
• Integrações — VTEX e Shopify via adapter pattern (Nuvemshop já entregue).
• Identity probabilística — unificação de contatos entre canais.
• Modo SaaS — self-service direto pra lojistas (hoje: BPO single-operator).

💬 Comunidade

• Discussões: GitHub Discussions — pra perguntas, ideias, showcase.
• Issues: GitHub Issues — bugs e tasks.
• Instagram: @melgarafael
• YouTube: youtube.com/@melgarafael

📜 Licença

Distribuído sob a licença MIT — veja LICENSE. Você pode usar, modificar
e distribuir livremente, inclusive comercialmente. O software é fornecido "como está",
sem garantias (ver cláusula de isenção no LICENSE).

🛟 Suporte & responsabilidades (self-host)

Este é um projeto self-host: cada pessoa roda o CRM na própria infraestrutura
(VPS, banco Supabase e chave de IA próprios). Isso implica:

• Suporte é comunitário e "as-is". Dúvidas e bugs entram como
  Issues ou
  Discussions. Não há SLA nem
  suporte garantido — é open source mantido por boa vontade.
• Você é responsável pela sua instalação. Atualizações não são automáticas
  (bash hostgator-setup-kit/update.sh quando quiser), e manter/backup do seu servidor
  é com você.
• LGPD — atenção: quem hospeda a instância é o controlador dos dados pessoais
  ali tratados (clientes, conversas, pedidos), com as obrigações legais decorrentes. Os
  mantenedores do projeto não têm acesso aos seus dados e não são controladores
  nem operadores da sua instância.
• Telemetria (Sentry): por padrão, erros anonimizados (CPF/telefone/e-mail
  removidos) são enviados ao Sentry da comunidade pra ajudar a corrigir bugs que afetam
  todos. Para desligar, use SENTRY_DSN=off no .env; para enviar ao seu Sentry,
  use SENTRY_DSN=<seu-dsn>. Ver lib/sentry/dsn.ts.

🙏 Agradecimentos

• WAHA (devlikeapro) — engine WhatsApp.
• Supabase — Postgres + Auth + Storage + Realtime numa stack só.
• Vercel — hosting + AI Gateway.
• Anthropic (Claude) — IA conversacional.
• shadcn/ui — base de componentes.
• Comunidade brasileira de e-commerce que validou as primeiras hipóteses.