melgarafael/deskcommcrm

Purpose and entry points

DeskcommCRM is a self-hostable, multi-tenant sales CRM centered on WhatsApp operations, with human attendants and AI agents sharing inbox, pipeline, and automation workflows. The Next.js App Router serves public auth, authenticated tenant UI, platform-admin UI, REST APIs, webhooks, cron endpoints, and MCP endpoints. Primary roots: app/layout.tsx, app/app/layout.tsx, app/api/v1/, app/admin/(protected)/.

Tenant security and persistence boundary

Supabase provides Postgres, Auth, Storage, Realtime, pgvector, and the tenant-isolation boundary through RLS. Server/browser/admin clients are separated in lib/supabase/server.ts, lib/supabase/browser.ts, and lib/supabase/admin.ts. The installable schema baseline is supabase/baseline.sql; incremental domain changes live in supabase/migrations/, including AI agents and follow-up flows. Authorization helpers enforce role and platform-admin boundaries in lib/auth/require-role.ts and lib/auth/requirePlatformAdmin.ts.

CRM and live-attendance core

The tenant application exposes Inbox, Contacts, Kanban/pipelines, team management, metrics, audit, settings, and LGPD operations under app/app/. Canonical business APIs are route handlers under app/api/v1/conversations/, app/api/v1/leads/, and app/api/v1/contacts/. Inbox operations include sending messages, assignment/claim/release/transfer, notes, snoozing, media, and retention; React clients use realtime-oriented hooks such as hooks/inbox/useConversationsRealtime.ts and hooks/inbox/useMessagesRealtime.ts.

Channels and message lifecycle

Channel adapters normalize WAHA and Meta Cloud WhatsApp behind lib/channels/index.ts, with implementations in lib/channels/adapters/waha.ts and lib/channels/adapters/meta-cloud.ts. Inbound provider webhooks enter through app/api/v1/webhooks/waha/[token]/route.ts or app/api/v1/webhooks/meta/[token]/route.ts, are validated/ingested, persisted as CRM conversations/messages, and become realtime-visible. Outbound messaging is mediated by messaging APIs and channel capability/pacing controls; media derives, persistence, transcription, and cleanup are handled by workers/media-persist-worker.ts, workers/media-derive-worker.ts, and workers/storage-cleanup-worker.ts.

AI-agent runtime and knowledge

The AI module configures versioned agents, credentials, providers, budgets, skills, routers, cases, memory, and RAG through app/api/v1/ai/ and the operator UI in app/app/ai/. The execution engine is centered in lib/agent-engine/agent/inbound-turn.ts, lib/agent-engine/agent/resolve-turn-agent.ts, and workers/agent-worker/main.ts: an inbound turn resolves an eligible agent, gathers CRM/knowledge context, invokes an LLM/provider, applies guardrails, and dispatches actions or a human handoff. RAG ingestion and embedding reside in lib/ai/rag/ and workers/rag-indexer.ts; model calls use Vercel AI SDK-compatible provider logic in lib/agent-engine/edge/llm/run-model-call.ts.

Automation, follow-ups, and asynchronous control flow

Domain events are recorded and drained rather than causing direct database-triggered HTTP calls. lib/event-log/drain.ts and app/api/v1/cron/event-log-drain/route.ts feed the automation engine in lib/automation/engine.ts. Public tenant capture webhooks enter at app/api/v1/webhooks/in/[token]/route.ts; rules can mutate CRM state, send WhatsApp, or invoke outbound webhooks. Follow-up graphs are authored in app/app/ai/followups/[id]/, validated/published by lib/followup/publish.ts, and executed by lib/followup/engine.ts via app/api/v1/cron/followup-flow-worker/route.ts. Routing, snooze, risk, LGPD, and agent dispatch have comparable cron/worker boundaries under app/api/v1/cron/ and workers/.

Governance, integrations, and deployment

Guardrails constrain AI sends, disclosure, LGPD basis, messaging windows, and promises in lib/agent-engine/guardrails/; auditing is centralized in lib/audit/index.ts. MCP exposes governed CRM tools through app/api/mcp/route.ts and lib/mcp/server.ts. Nuvemshop OAuth/webhooks are isolated in lib/nuvemshop/ and app/api/v1/webhooks/nuvemshop/. Runtime is Node 22, Next.js 16/React 19, TypeScript, and Docker; Dockerfile runs the application while Dockerfile.worker supports worker execution. Deployment options include Vercel plus a WhatsApp VPS, or the self-host stack orchestrated by docker-compose.yml and hostgator-setup-kit/install.sh. External services include Supabase, WAHA, AI providers/AI Gateway, Upstash Redis, Resend, Sentry, and Nuvemshop.