Portal Digincrease — Documentación técnica

Visión general

El Portal de Digincrease es una plataforma SaaS multi-tenant para agencias de marketing. Permite gestionar clientes, contenido, facturación, inbox omnicanal y automatizaciones de respuesta con IA.

Arquitectura

El sistema corre en un único VPS con Docker Compose. Caddy actúa como reverse proxy con SSL automático.

  ┌─────────────────────────────────────────────────────┐
  │                   VPS (tu-servidor-ip)               │
  │                                                     │
  │  Caddy (443/80)                                     │
  │   ├── portal.tudominio.com  → :3005 (Next.js)       │
  │   ├── docs.tudominio.com    → :3005/docs             │
  │   └── automation.tudominio.com → :5678 (n8n)        │
  │                                                     │
  │  Docker Compose                                     │
  │   ├── web  (node:20 / Next.js)  → puerto 3005       │
  │   └── postgres (PostgreSQL 15)  → interno           │
  └─────────────────────────────────────────────────────┘

  Flujo de mensaje entrante (WhatsApp):
  ┌──────────┐    ┌──────────────┐    ┌──────────┐
  │ Usuario  │───▶│  Meta Cloud  │───▶│  Portal  │
  │ WhatsApp │    │  API Webhook │    │/api/     │
  └──────────┘    └──────────────┘    │webhooks/ │
                                      │meta      │
                                      └────┬─────┘
                                           │ guarda en DB
                                           │ reenvía a n8n
                                      ┌────▼─────┐
                                      │   n8n    │
                                      │ AI Agent │
                                      └────┬─────┘
                                           │ POST /api/v1/...
                                      ┌────▼─────┐
                                      │  Portal  │
                                      │ API send │
                                      └────┬─────┘
                                           │
                                      ┌────▼──────┐
                                      │  Meta API │
                                      │ /messages │
                                      └───────────┘

Base de datos

PostgreSQL gestionado con Prisma ORM. El schema completo está en prisma/schema.prisma. Los comandos de migración se ejecutan con prisma db push dentro de un container efímero node:20-alpine.

Agency

Tabla raíz del sistema. Cada agencia tiene sus propios clientes, configuración de canales y datos de facturación.

Client

Clientes que pertenecen a una agencia. Cada cliente tiene su propio portal de acceso.

User

InboxConversation

InboxContact

InboxMessage

SocialAccount

Diagrama de base de datos

Estructura visual de las tablas y sus relaciones. Las flechas indican claves foráneas (FK). Los campos con ? son opcionales.

API Reference

Todas las rutas bajo /api/admin/* requieren sesión NextAuth con role: admin. Las rutas /api/portal/* requieren role: client.

Inbox — Admin

Clientes — Admin

Configuración — Admin

Webhooks — Públicos

Automatización — API compatible con Chatwoot

Portal — Client

Meta Webhooks

Configuración en Meta Developer

La misma URL y token se usa para todos los canales (WhatsApp, Messenger, Instagram).

Routing por objeto

POST /api/webhooks/meta
body.object === 'page'                    → Messenger handler
body.object === 'instagram'               → Instagram handler
body.object === 'whatsapp_business_account' → WhatsApp handler

Lookup de agencia para WhatsApp

WhatsApp no tiene OAuth como Instagram/Facebook, por lo que no existe SocialAccount. El handler busca la agencia por el phoneNumberId guardado en Agency.channelConfig:

// 1. Buscar en SocialAccount (por si hay cuenta vinculada)
// 2. Fallback: buscar agencia donde channelConfig.whatsapp.phoneNumberId === phoneNumberId
const match = agencies.find(a => a.channelConfig?.whatsapp?.phoneNumberId === phoneNumberId)

Automatización n8n

Flujo completo

1. WhatsApp → Meta Cloud → POST /api/webhooks/meta
2. Portal guarda mensaje en InboxMessage (direction: inbound)
3. Portal hace POST a AUTOMATION_WEBHOOK_URL con formato Chatwoot-compatible:
   {
     body: {
       message_type: "incoming",
       content: "texto del mensaje",
       content_type: "text",
       conversation: {
         id: "<conversationId>",               ← UUID del portal, no número
         meta: { sender: { phone_number: "+54911XXXXXXXX", name: "Nombre del contacto" } },
         labels: [],
         messages: [{ sender: { phone_number: "+54911XXXXXXXX" } }]
       },
       account: { id: "<agencyId>" }
     }
   }
4. n8n AI Agent procesa y llama al portal:
   POST /api/v1/accounts/{agencyId}/conversations/{conversationId}/messages
   Header: api_access_token: <PORTAL_API_TOKEN>
   Body: { content: "respuesta del bot", message_type: "outgoing" }
5. Portal envía via WhatsApp Cloud API y guarda en InboxMessage (direction: outbound)

Cambios en el nodo "Enviar a Chatwoot1"

El resto del flujo n8n (Redis buffer, AI Agent, Airtable, Google Calendar) no requiere cambios.

Variables relevantes en n8n

Sistema de Inbox

Arquitectura del inbox

El inbox es multi-canal y multi-tenant. Cada conversación pertenece a una agencia y opcionalmente a un cliente específico.

InboxContact (1) ──── (N) InboxConversation (1) ──── (N) InboxMessage
                              │
                              ├── agencyId  (siempre presente)
                              └── clientId  (opcional, para inbox por cliente)

Unread count

Los mensajes inbound tienen readAt: null hasta que el admin abre la conversación. El endpoint GET con conversationId los marca como leídos automáticamente.

Auto-refresh

El frontend hace polling cada 3 segundos mientras hay una conversación activa. El scroll automático solo se activa si el usuario está en el fondo del chat.

Envío optimista

Al enviar, el mensaje aparece inmediatamente con opacidad reducida (estado temporal) mientras se procesa el POST. Luego se reemplaza con el dato real del servidor.

Variables de entorno

Archivo .env en /home/ubuntu/marketing-portal/ en el VPS.

Comandos útiles en VPS

# Ver logs en tiempo real
ssh -i ~/tu-ssh-key.pem ubuntu@TU_VPS_IP \
  "docker logs -f nombre-del-container-web"

# Rebuild y deploy
cd /home/ubuntu/tu-proyecto
docker compose build --no-cache && docker compose up -d

# Aplicar cambios de schema Prisma
APP=/home/ubuntu/tu-proyecto
docker run --rm --network tu-proyecto_net \
  -v $APP/prisma:/app/prisma \
  -e DATABASE_URL='postgresql://USER:PASSWORD@postgres:5432/DB_NAME' \
  -w /app node:20-alpine sh -c \
  'apk add -q openssl && npm install -g prisma@5 && prisma db push --skip-generate'

# Consultar DB directamente
docker exec nombre-del-container-postgres psql -U postgres nombre_db -c "SELECT ..."