CRM operacional multi-tenant para e-commerce, com IA conversacional nativa, WhatsApp via WAHA e LGPD by-design.
📘 Setup Guide · 🏗️ Arquitetura · 🤝 Contribuir · 📋 PRDs · 🗺️ Roadmap
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)
DeskcommCRM unifica atendimento humano, chatbot 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.
- 🤖 IA operando o atendimento com RAG por tenant — 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/redactecustomer/data_requestda Nuvemshop como contrato de primeira-classe; anonimização preferida sobre delete; audit append-only com retenção 5 anos. - 🔌 MCP-ready (Fase 2) — exporta capabilities pro ecossistema de agentes.
- 🏢 Multi-tenant de verdade — RLS em toda tabela tenant-aware, teste de isolamento como gate de CI.
# 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 devApp: 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.
| Camada | Escolha | Por quê |
|---|---|---|
| Frontend | Next.js 15 App Router + TypeScript estrito | Server Components + Route Handlers no mesmo repo |
| Estilo | Tailwind + shadcn/ui (new-york, neutral) |
Customizável sem lock-in |
| DB | Supabase (Postgres + RLS + vector) |
Multi-tenant nativo, embedding pra RAG |
| Auth | Supabase Auth via @supabase/ssr |
Cookie SameSite=Strict, HttpOnly |
| Realtime | Supabase Realtime | postgres_changes + broadcast |
| Storage | Supabase Storage (URLs assinadas) | Bucket privado whatsapp-media |
| WAHA Plus (engine NOWEB) | Multi-tenant, retry, S3 | |
| Filas | event_log table + workers (cron) |
Sem Inngest/Trigger no MVP |
| Rate limit | Upstash Redis (sliding window) | Serverless, free tier suficiente |
| AI | Vercel AI Gateway (Anthropic primário, OpenAI embeddings) | Fallback automático, ZDR |
| Validação | Zod | Input externo, env, payloads |
| Observability | Sentry (com beforeSend sanitizado) |
Sem PII no breadcrumb |
| Hospedagem | Vercel (app) + Hostgator VPS Turing/SP (WAHA) | Edge + dedicado pra WhatsApp; datacenter Brasil |
Detalhes: ARCHITECTURE.md.
DeskcommCRM/
├── app/ # Next.js App Router
│ ├── (admin)/ # Rotas super-admin (impersonate, tenants)
│ ├── (public)/ # Login, recovery
│ ├── app/ # Rotas autenticadas (inbox, kanban, contacts, audit)
│ └── api/v1/ # API REST canônica
├── components/ # React (ui/, empty/, feedback/, shell/)
├── lib/ # supabase/, waha/, ai/, api/, logger.ts, env.ts
├── hooks/
├── supabase/migrations/ # SQL versionado
├── tests/{e2e,unit}/
├── scripts/ # seeds, qa-waves, manutenção
├── docs/ # PRDs, specs, stories, SETUP.md
├── workers/ # consumers de event_log
└── tasks/ # backlog ativo
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.
Tab/Shift+Tab— navegação focável (login, formulários, kanban cards)Enter— confirma ações primáriasEsc— fecha dialogs/sheets
Documentação completa de keyboard shortcuts vem com EPIC-04 (kanban) e EPIC-03 (inbox).
| Doc | O que tem |
|---|---|
docs/SETUP.md |
Setup completo passo a passo de todas as integrações |
CLAUDE.md |
Convenções não-negociáveis (leitura obrigatória pra contribuir) |
ARCHITECTURE.md |
Visão de 1 página da arquitetura |
CONTRIBUTING.md |
Fluxo PR + epic-executor |
docs/prd/ |
PRDs (master, platform, customer 360, WhatsApp, pipeline, IA-RAG, Nuvemshop) |
docs/specs/ |
Specs técnicas detalhadas (schema SQL, payloads exatos) |
docs/business-rules/ |
Regras de negócio fora do código |
docs/stories/epics/MASTER.md |
Plano de execução wave-by-wave |
docs/DEPLOY-CHECKLIST.md |
Preflight pré-go-live |
docs/runbooks/waha-hostgator.md |
Runbook completo de WAHA em produção (VPS Hostgator) |
Esse projeto é open source pra comunidade. Toda contribuição é bem-vinda — desde fix de typo em doc até epic novo.
Antes de abrir PR:
- Leia
CLAUDE.md(~5 min) — convenções não-negociáveis (multi-tenancy, RLS, audit, LGPD). - Leia
CONTRIBUTING.md— fluxo de branches, commits, epic-executor. - Identifique o epic em
docs/stories/epics/MASTER.md.
Fluxo curto:
git checkout -b feat/EPIC-XX-short-slug
# implementa + testes
pnpm typecheck && pnpm lint && pnpm test:unit
git commit -m "feat(EPIC-XX): descrição"
# abre PRDefinition of Done: typecheck zero, lint zero, testes relevantes verdes, RLS testada se toca tabela tenant-aware, audit log emitido em mutações, sem console.log esquecido. Detalhes em CLAUDE.md.
Abra uma issue com:
- Versão do Node, pnpm e SO.
- Output do
/api/v1/health. - Stack trace ou screenshot.
- Steps to reproduce.
Pra vulnerabilidades de segurança, NÃO abra issue pública. Mande email pra [email protected] (a definir) ou DM ao mantenedor.
- ✅ Fase 1 — MVP (8–12 semanas): Auth, multi-tenancy, inbox WhatsApp, kanban, customer 360, RAG, integração Nuvemshop, LGPD.
- 🔜 Fase 1.5 — Hardening (+4–8 semanas): observability, performance, anti-banimento avançado.
- 🔜 Fase 2 — Escala: MCP público, identity probabilística, integrações VTEX/Shopify, modo SaaS direto.
Detalhe wave-by-wave: docs/stories/epics/MASTER.md.
- Discussões: GitHub Discussions — pra perguntas, ideias, showcase.
- Issues: GitHub Issues — bugs e tasks.
- Twitter / X: @rafaelmelgaco (a confirmar).
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).
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.shquando 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=offno.env; para enviar ao seu Sentry, useSENTRY_DSN=<seu-dsn>. Verlib/sentry/dsn.ts.
- 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.
Built with ☕ in Brasil · Made for the community