LunaCRM

CRM multi-tenant SaaS pra atendimento WhatsApp com IA. Triagem inicial automática, perfilamento progressivo de clientes, handoff humano com assistência de IA.

Stack principal

Camada	Tecnologia
Frontend	Next.js 16 (App Router, SSR-first)
Backend	Elysia.js sobre Bun
ORM	Drizzle ORM
Database	PostgreSQL Neon (serverless)
Cache/Queue	Redis 7 + BullMQ
Real-time	Socket.io (porta separada)
Auth	Better Auth + Organization plugin (httpOnly cookies)
AI	Anthropic SDK (Claude)
WhatsApp	Evolution API self-hosted (Docker)
Validação	Zod (package shared)
UI	Tailwind v4 + shadcn/ui
Monorepo	Turborepo

Estrutura monorepo

lunacrm/
├── apps/
│   ├── web/    # Next.js 16
│   └── api/    # Elysia.js (Bun)
├── packages/
│   ├── shared/ # Zod schemas, types
│   └── ui/     # design system
└── docker-compose.yml

Arquitetura API (apps/api/src/)

• index.ts — entrypoint Elysia, registra rotas, sobe Socket.io e workers BullMQ
• routes/ — handlers thin agrupados em /api/*
• services/ — lógica de negócio, queries Drizzle, regras tenant
• plugins/ — pipeline auth → tenant → rbac → limits
• queue/workers/ — ai-analysis, ai-profile-update, ai-response
• lib/ — db.ts (Drizzle), auth.ts (Better Auth), evolution.ts, redis.ts, socket.ts, ai.ts
• drizzle/schema/ — schema TS (cuid IDs, snake_case, created_at/updated_at)

Auth

• Better Auth catch-all em /api/auth/* (sign-in/up/session/org)
• Sessão httpOnly cookie → tenantPlugin extrai {userId, tenantId, role, branchId}
• Roles: superadmin > owner > admin > agent

Multi-tenant (regra crítica)

• Toda tabela business tem tenant_id
• Toda query filtra por tenant_id — nunca confiar no client
• tenantId derivado da active organization Better Auth

Webhooks

webhooksRoutes montado fora do grupo /api (público, sem auth). Evolution entra aí.

Frontend integra via Eden Treaty (export type App no index.ts).

Infra produção

• VPS Hermes: 187.127.24.217 (SSH root)
• App path: /home/lunacrm/app/
• Domínios: luna.kodama.solutions (web), api.luna.kodama.solutions (API)
• Reverse proxy: nginx native
• Cloudflare CDN/SSL na frente
• CI/CD: GitHub Actions → GHCR → SSH deploy
• .env.production no VPS, COOKIE_DOMAIN=.luna.kodama.solutions

Postgres na VPS — atenção

App LunaCRM NÃO usa postgres da VPS. Roda em Neon (serverless).

Container lunacrm-evolution-db (postgres:17-alpine) na VPS é isolado, exclusivo da Evolution API. Nada do app principal conecta nele.

Convenções

• Comunicação user: pt-BR
• Código/commits/PRs/identifiers: inglês
• UI text: pt-BR (target Brasil)
• DB: snake_case plural (leads, conversations, ai_profile_updates)
• Sem any exceto JSON dinâmico
• Named exports

Status fases

Todas concluídas (1-6: core multi-tenant, Evolution, conversations real-time, AI engine, AI chatbot, superadmin/billing/landing). Foco atual: SSR migration, polish, prod readiness.