� RestauBot - Sistema Inteligente de Gestión de Pedidos con WhatsApp

📋 Descripción General

RestauBot es una solución completa de gestión de restaurantes que centraliza y automatiza los pedidos recibidos vía WhatsApp. El proyecto combina un chatbot con inteligencia artificial (Google Gemini) y un dashboard web administrativo que sincroniza automáticamente todos los pedidos en tiempo real.

🎯 Objetivo Principal

Gestión centralizada de pedidos de restaurante mediante sincronización automática desde WhatsApp, permitiendo a los propietarios y empleados administrar todos sus pedidos (tanto automáticos del chatbot como manuales) desde una única aplicación web, mejorando la eficiencia operativa y la experiencia del cliente.

🚀 Características Principales

Sincronización WhatsApp: Todos los pedidos de WhatsApp se sincronizan automáticamente en el dashboard
Chatbot IA para Pedidos: Los clientes pueden hacer pedidos completos conversando naturalmente con el bot
Gestión Unificada: Dashboard único para pedidos de WhatsApp, manuales y otros canales
Tiempo Real: Actualización instantánea de pedidos y estados vía WebSockets
Multi-Establecimiento: Soporte para gestionar múltiples restaurantes desde una cuenta
Analytics y KPIs: Métricas en tiempo real sobre ventas, productos más vendidos y rendimiento
Control de Catálogo: Gestión completa de productos, menús y precios
Sistema de Horarios: Apertura/cierre automático por establecimiento

🏗️ Arquitectura del Sistema

El proyecto está estructurado como un monorepo con dos aplicaciones principales:

kebab-chatbot-monorepo/
├── chatbot-gemini/          # Backend - WhatsApp Bot + IA
├── kebab-chatbot-ai/        # Frontend - Dashboard Next.js
└── docker-compose.yml       # Orquestación de servicios

📦 Componentes Principales

1. chatbot-gemini (Backend)

Tecnología: Node.js + TypeScript + Express
IA: Google Gemini 2.0 Flash
WhatsApp: whatsapp-web.js con autenticación remota
Base de Datos: Supabase con PostgreSQL
WebSockets: Socket.io para comunicación en tiempo real
Puerto: 8080

Funcionalidades principales:

Gestión multi-sesión de WhatsApp por establecimiento
Procesamiento de mensajes con IA conversacional
Generación y validación de pedidos
Sincronización de sesiones en Supabase Storage
API REST para control del bot

2. kebab-chatbot-ai (Frontend)

Framework: Next.js 15 (App Router)
UI: React 19 + TailwindCSS 4 + shadcn/ui
Autenticación: Supabase Auth
Estado Global: Zustand
Gráficos: Recharts
Validación: Zod
Puerto: 3000

Módulos principales:

Dashboard: Métricas, KPIs y gráficos en tiempo real
Pedidos: Gestión y seguimiento de pedidos (WhatsApp y manuales)
Chat: Visualización de conversaciones con clientes
Catálogo: Gestión de productos y menús
Configuración: Establecimientos, empleados y horarios
WhatsApp: Panel de conexión y estado del bot

🚀 Instalación y Configuración

Prerrequisitos

Node.js: v20 o superior
Docker & Docker Compose: Para despliegue con contenedores
Cuenta Supabase: Proyecto configurado con PostgreSQL (supabase.com)
Google Gemini API Key: Para funcionalidades de IA conversacional

Variables de Entorno

chatbot-gemini/.env

# Supabase
SUPABASE_URL=https://tu-proyecto.supabase.co
SUPABASE_SERVICE_ROLE_KEY=tu_service_role_key

# Google Gemini
GOOGLE_API_KEY=tu_google_api_key

# Bot Configuration
BOT_PORT=8080

kebab-chatbot-ai/.env.local

# Supabase (Cliente)
NEXT_PUBLIC_SUPABASE_URL=https://tu-proyecto.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=tu_anon_key

# Supabase (Servidor)
SUPABASE_SERVICE_ROLE_KEY=tu_service_role_key

# Backend API
NEXT_PUBLIC_BACKEND_URL=http://localhost:8080

# Next.js
NEXT_PUBLIC_BASE_URL=http://localhost:3000

🐳 Instalación con Docker (Recomendado)

Clonar el repositorio

git clone <repository-url>
cd kebab-chatbot-monorepo

Configurar variables de entorno

# Crear archivos .env en ambos proyectos
cp chatbot-gemini/.env.example chatbot-gemini/.env
cp kebab-chatbot-ai/.env.local.example kebab-chatbot-ai/.env.local
# Editar y completar las variables

Construir y ejecutar con Docker Compose

docker-compose up -d

Verificar que los servicios estén corriendo

docker-compose ps

URLs de acceso:

Frontend (Local): http://localhost:3000
Frontend (Producción): https://kebab-frontend.graysky-c9660da6.spaincentral.azurecontainerapps.io
Backend (Local): http://localhost:8080
Health Check Backend: http://localhost:8080/health

💻 Instalación Local (Desarrollo)

Backend (chatbot-gemini)

cd chatbot-gemini
npm install
npm run dev  # Modo desarrollo con hot-reload
# o
npm run build && npm start  # Producción

Frontend (kebab-chatbot-ai)

cd kebab-chatbot-ai
npm install
npm run dev  # Modo desarrollo (Turbopack)
# o
npm run build && npm start  # Producción

📊 Base de Datos (Supabase PostgreSQL)

RestauBot utiliza Supabase como backend, que proporciona una base de datos PostgreSQL gestionada con características de tiempo real, autenticación integrada y almacenamiento de archivos.

Tablas Principales

Tabla	Descripción	Sincronización
`establishments`	Establecimientos/restaurantes	-
`users`	Usuarios del sistema (empleados/admins)	-
`establishment_users`	Relación entre usuarios y establecimientos	-
`products`	Productos del catálogo	✅ Usado por chatbot
`menus`	Menús (combos de productos)	✅ Usado por chatbot
`menu_products`	Productos que componen cada menú	✅ Usado por chatbot
`orders`	Pedidos sincronizados (WhatsApp, manual, web)	✅ Tiempo real
`order_items`	Items de cada pedido	✅ Tiempo real
`chats`	Conversaciones con clientes vía WhatsApp	✅ Tiempo real
`chat_history`	Mensajes del historial de chat	✅ Tiempo real
`schedules`	Horarios de apertura/cierre por establecimiento	✅ Usado por chatbot

Sincronización en Tiempo Real

El sistema aprovecha las capacidades de Realtime de Supabase PostgreSQL para:

Pedidos: Cuando el chatbot crea un pedido desde WhatsApp, aparece instantáneamente en el dashboard
Estados: Cambios de estado de pedidos se reflejan en todas las sesiones abiertas
Mensajes: Conversaciones de WhatsApp se sincronizan en tiempo real
Métricas: KPIs y gráficos se actualizan automáticamente

Row Level Security (RLS)

El proyecto utiliza políticas RLS de PostgreSQL (implementadas en Supabase) para seguridad a nivel de fila:

Los usuarios solo pueden acceder a datos de sus establecimientos asignados
El backend usa SERVICE_ROLE_KEY para operaciones sin restricciones (chatbot)
El frontend usa ANON_KEY con políticas RLS activas

🤖 Flujo del Chatbot con IA

Proceso de Conversación

graph TD
    A[Cliente envía mensaje por WhatsApp] --> B{Bot activo?}
    B -->|No| C[Mensaje ignorado]
    B -->|Sí| D{Establecimiento abierto?}
    D -->|No| E[Respuesta: Cerrado]
    D -->|Sí| F[Guardar mensaje en BD]
    F --> G[Cargar historial de conversación]
    G --> H[Enviar a Gemini AI]
    H --> I{Requiere función?}
    I -->|Sí - get_catalog| J[Consultar catálogo]
    I -->|Sí - get_schedule| K[Consultar horarios]
    I -->|Sí - create_order| L[Crear pedido]
    I -->|No| M[Generar respuesta]
    J --> H
    K --> H
    L --> N[Confirmar pedido al cliente]
    M --> N
    N --> O[Enviar respuesta por WhatsApp]

Function Calling (Gemini AI)

El chatbot utiliza Function Calling de Google Gemini para interactuar con la base de datos:

Función	Descripción	Uso
`get_establishment_snapshot`	Obtiene información del establecimiento	Inicio de conversación
`get_schedule_by_establishment_id`	Consulta horarios de apertura	Cuando cliente pregunta por horarios
`get_catalog_establishment`	Obtiene productos y menús disponibles	Cliente consulta carta
`create_full_order`	Crea un pedido completo	Cliente confirma su orden

Características de la IA

Contexto conversacional: Mantiene historial de últimos 20 mensajes
Multi-idioma: Responde en el idioma del cliente
Validación de pedidos: Verifica disponibilidad y precios
Gestión de errores: Manejo robusto de errores y respuestas de fallback
Conversaciones naturales: Interacción fluida y humana

🖥️ Dashboard - Funcionalidades

📈 Dashboard Principal

KPIs en tiempo real:
- Pedidos del día
- Pedidos completados
- Ticket promedio
- Ventas totales del día
Gráficos:
- Distribución de pedidos por hora
- Productos más vendidos
Actualización en tiempo real con WebSockets

📦 Gestión de Pedidos (Sincronización Central)

El corazón de RestauBot: todos los pedidos en un solo lugar, sin importar su origen.

Sincronización Automática: Pedidos de WhatsApp aparecen automáticamente en el dashboard
Fuentes Unificadas:
- whatsapp: Pedidos del chatbot IA
- manual: Creados por empleados en el dashboard
- web: Futuros pedidos online
Estados del Ciclo de Vida: pending, in_progress, ready, delivered, cancelled
Tipos de Cumplimiento: delivery, pickup, dine_in
Creación Manual: Los empleados pueden crear pedidos desde el dashboard
Actualización en Tiempo Real: Cambios instantáneos vía WebSockets
Vista Unificada: Todos los pedidos (WhatsApp + manuales) en una sola interfaz

💬 Chat

Visualización de todas las conversaciones
Historial completo de mensajes
Identificación de mensajes del cliente vs bot
Búsqueda y filtrado

🍽️ Catálogo

Productos:
- Gestión CRUD completa
- Categorías: entrante, principal, postre, bebida, extra
- Precios y descripciones
- Disponibilidad
Menús:
- Combos de productos
- Precio especial de menú
- Gestión de productos incluidos

⚙️ Configuración

Establecimientos:
- Datos de contacto
- Configuración de envíos
- Logo y branding
Empleados:
- Gestión de usuarios
- Roles y permisos
- Asignación a establecimientos
Horarios:
- Configuración por día de la semana
- Múltiples franjas horarias
- Apertura/cierre automático

📱 WhatsApp

Conexión QR: Escaneo de código QR para vincular WhatsApp
Estados:
- not_initialized
- initializing
- qr_generated
- ready
- error
Control del bot: Activar/desactivar respuestas automáticas
Multi-sesión: Cada establecimiento tiene su propia sesión independiente
Persistencia: Sesiones guardadas en Supabase Storage

🔌 API del Backend

Endpoints Principales

Gestión de Sesiones WhatsApp

POST /stores/:storeId/init
GET  /stores/:storeId/status
POST /stores/:storeId/logout
POST /stores/:storeId/destroy
POST /stores/:storeId/activeBot
POST /stores/:storeId/deactivateBot

Envío de Mensajes

POST /send
Content-Type: application/json

{
  "storeId": "uuid-del-establecimiento",
  "to": "34612345678",
  "message": "¡Tu pedido está listo!"
}

Health Check

GET /health

WebSockets (Socket.io)

Namespaces dinámicos por establecimiento:

/ws/:establishmentId

Eventos emitidos:

status: Cambio de estado del cliente WhatsApp
qr: Nuevo código QR generado
bot_active: Estado del bot (activo/inactivo)

Eventos recibidos:

connection: Cliente conectado
disconnect: Cliente desconectado

🔐 Autenticación y Seguridad

Supabase Auth

Sistema: Email + Password
Flujos soportados:
- Login
- Registro
- Recuperación de contraseña
- Actualización de perfil
Middleware: Protección de rutas en Next.js
Server Actions: Acciones del servidor seguras

Row Level Security (RLS)

Usuarios solo acceden a datos de sus establecimientos
Políticas configuradas en Supabase
Validación en servidor y cliente

Docker Security

Variables de entorno en archivos .env (no en imagen)
Volúmenes montados en modo read-only cuando es posible
Red aislada para comunicación entre contenedores
Health checks para monitoreo

🛠️ Tecnologías Utilizadas

Backend

Runtime: Node.js 20+ con TypeScript
Framework: Express 5
IA: Google Gemini 2.0 Flash
WhatsApp: whatsapp-web.js + Puppeteer
Base de Datos: Supabase (PostgreSQL)
WebSockets: Socket.io
Build: tsc + tsx

Frontend

Framework: Next.js 15 (App Router, RSC)
UI: React 19
Styling: TailwindCSS 4 + shadcn/ui
Estado: Zustand
Validación: Zod
Gráficos: Recharts
Icons: Lucide React
Notificaciones: Sonner

DevOps

Containerización: Docker + Docker Compose
Registro: GitHub Container Registry (ghcr.io)
Monitoreo: Health checks automáticos
Logs: Volúmenes persistentes

📁 Estructura de Directorios Detallada

Backend (chatbot-gemini)

chatbot-gemini/
├── src/
│   ├── index.ts              # Servidor principal y WebSockets
│   ├── whatsappDB.ts         # Comandos de WhatsApp
│   ├── ai/
│   │   ├── ai.ts             # Lógica de conversación con Gemini
│   │   └── utils/
│   │       ├── functionDeclarations.ts  # Definiciones de funciones
│   │       ├── functionCalls.ts         # Ejecución de funciones
│   │       └── utils.ts                 # Utilidades (horarios, etc.)
│   ├── supabase/
│   │   ├── supabase.ts              # Cliente de Supabase
│   │   ├── supabase-store.ts        # Storage para sesiones WhatsApp
│   │   └── databaseRepository.ts    # Consultas a BD
│   └── types/
│       └── database.types.ts        # Tipos generados de Supabase
├── Dockerfile
└── package.json

Frontend (kebab-chatbot-ai)

kebab-chatbot-ai/
├── app/
│   ├── layout.tsx                   # Layout principal
│   ├── page.tsx                     # Página de inicio
│   ├── api/                         # API Routes
│   │   ├── auth/                    # Endpoints de autenticación
│   │   └── stores/                  # Proxy a backend
│   ├── auth/                        # Páginas de autenticación
│   ├── login/
│   ├── onboarding/                  # Primer acceso
│   └── dashboard/                   # Panel administrativo
│       ├── page.tsx                 # Dashboard principal
│       ├── orders/                  # Gestión de pedidos
│       ├── chat/                    # Conversaciones
│       ├── catalog/                 # Productos y menús
│       ├── settings/                # Configuración
│       └── establishment/           # Datos del establecimiento
├── components/
│   ├── ui/                          # Componentes de shadcn/ui
│   ├── dashboard/                   # Componentes del dashboard
│   ├── chat/                        # Componentes de chat
│   ├── provider/                    # Context providers
│   └── ...                          # Otros componentes
├── lib/
│   ├── utils.ts                     # Utilidades generales
│   └── i18n.ts                      # Internacionalización
├── utils/
│   ├── services/                    # Servicios de datos
│   └── supabase/                    # Cliente y servidor Supabase
├── stores/                          # Zustand stores
├── types/                           # Tipos TypeScript
├── hooks/                           # Custom hooks
└── public/                          # Assets estáticos

🧪 Testing y Desarrollo

Modo Desarrollo

Backend

cd chatbot-gemini
npm run dev  # tsx --watch

Hot-reload automático con tsx.

Frontend

cd kebab-chatbot-ai
npm run dev  # next dev --turbopack

Turbopack para compilación ultra-rápida.

Build de Producción

# Backend
cd chatbot-gemini
npm run build
npm start

# Frontend
cd kebab-chatbot-ai
npm run build
npm start  # Utiliza .next/standalone

Linting

cd kebab-chatbot-ai
npm run lint  # ESLint 9

🚢 Despliegue

Despliegue en Producción

Producción Actual

URL: https://kebab-frontend.graysky-c9660da6.spaincentral.azurecontainerapps.io
Plataforma: Azure Container Apps
Región: Spain Central

Docker Compose

El archivo docker-compose.yml está configurado para producción con:

Health checks para ambos servicios
Restart policy: unless-stopped
Volúmenes persistentes para:
- Sesiones de WhatsApp
- Cache de WhatsApp
- Logs del chatbot
Red privada para comunicación segura
Imágenes en GHCR: ghcr.io/aek676/kebab-chatbot-ai:latest

Comandos Útiles

# Iniciar servicios
docker-compose up -d

# Ver logs
docker-compose logs -f

# Reiniciar un servicio
docker-compose restart kebab-backend

# Detener todo
docker-compose down

# Limpiar volúmenes (cuidado!)
docker-compose down -v

Variables de Entorno en Producción

Asegúrate de:

No commitear archivos .env
Usar secretos seguros en producción
Configurar CORS adecuadamente
Usar HTTPS en URLs públicas

🐛 Troubleshooting

El bot de WhatsApp no conecta

Verificar logs del contenedor
```
docker-compose logs chatbot-gemini
```
Comprobar que Puppeteer tiene dependencias
- El Dockerfile incluye todas las dependencias necesarias
Versión de WhatsApp Web
- El bot usa versión pinned: 2.3000.1026163538
- Si falla, actualizar PINNED_WWEB_VERSION en index.ts

Sesión corrupta

Eliminar volumen de auth:

docker volume rm kebab-chatbot-monorepo_whatsapp_auth

Error de CORS en el frontend

Verificar que NEXT_PUBLIC_BACKEND_URL apunte correctamente

En el backend, ajustar configuración de Socket.io:

const io = new SocketIOServer(server, { 
  cors: { origin: process.env.FRONTEND_URL } 
});

Base de datos: errores de permisos

Verificar que las políticas RLS estén configuradas
Usar SUPABASE_SERVICE_ROLE_KEY en el backend (bypass RLS)
Usar NEXT_PUBLIC_SUPABASE_ANON_KEY en el frontend

Mensajes no se procesan

Verificar que el bot esté activo:

curl http://localhost:8080/stores/{storeId}/status

Activar el bot:

curl -X POST http://localhost:8080/stores/{storeId}/activeBot

Comprobar que el establecimiento esté abierto (tabla schedules)

📝 Roadmap y Próximas Mejoras

🎯 Prioridad Alta - Mejoras de Sincronización

Sincronización bidireccional: responder desde el dashboard a WhatsApp
Notificaciones push cuando llega un pedido nuevo
Confirmación automática de pedido al cliente vía WhatsApp
Estados de lectura de mensajes

📊 Analytics y Reportes

Exportación de reportes (PDF/Excel)
Panel de analytics avanzado
Comparativas por períodos
Análisis de clientes frecuentes

💰 Pagos y Entregas

Integración con sistemas de pago online
Integración con plataformas de delivery (Glovo, Uber Eats)
Seguimiento de repartidores

📱 Multicanal

App móvil nativa (React Native) para gestores
Multi-canal: Telegram, Instagram, Facebook Messenger
Pedidos desde web pública (integración con sitio del restaurante)

🎁 Fidelización y CRM

Sistema de fidelización de clientes
Programa de puntos y descuentos
CRM integrado con historial de clientes
Campañas de marketing automatizadas

🏪 Gestión Avanzada

Reservas de mesas
Gestión de inventario
Control de costes y rentabilidad por producto
Múltiples idiomas (inglés, francés, árabe)

🤝 Contribución

Guía de Estilo

Ver kebab-chatbot-ai/docs/GUIA DE ESTILO.md para convenciones de código.

Flujo de Trabajo

Fork del repositorio
Crear rama feature: git checkout -b feature/nueva-funcionalidad
Commits con mensajes descriptivos
Push a tu fork: git push origin feature/nueva-funcionalidad
Crear Pull Request

📄 Licencia

🎯 Caso de Uso Principal

Flujo Completo de un Pedido por WhatsApp

Cliente contacta por WhatsApp → Escribe al número del restaurante
Chatbot IA responde → Saluda y muestra el catálogo disponible
Cliente hace pedido conversando → "Quiero un kebab completo y una coca cola"
IA procesa y confirma → Valida productos, precio y tipo de entrega
Pedido creado automáticamente → Se guarda en PostgreSQL (Supabase)
✨ Sincronización instantánea → Aparece en el dashboard del restaurante
Empleado gestiona → Ve el pedido, cambia estado, prepara comida
Cliente recibe actualizaciones → (Futuro) Notificaciones de estado
Pedido completado → Métricas actualizadas en tiempo real

Todo sincronizado sin intervención manual 🚀

👥 Contacto y Soporte

Para preguntas, sugerencias o soporte técnico:

🐛 Issues: GitHub Issues
📚 Documentación: Ver carpeta docs/
🌐 Producción: https://kebab-frontend.graysky-c9660da6.spaincentral.azurecontainerapps.io

🙏 Agradecimientos

Next.js - Framework React
Supabase - Backend as a Service
Google Gemini - IA Conversacional
whatsapp-web.js - Cliente WhatsApp
shadcn/ui - Componentes UI

RestauBot - Sincroniza tus pedidos de WhatsApp automáticamente 🤖💬

Hecho con ❤️ para restaurantes que quieren automatizar y centralizar sus pedidos

⬆ Volver arriba

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
chatbot-gemini		chatbot-gemini
kebab-chatbot-ai		kebab-chatbot-ai
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation

� RestauBot - Sistema Inteligente de Gestión de Pedidos con WhatsApp

📋 Descripción General

🎯 Objetivo Principal

🚀 Características Principales

🏗️ Arquitectura del Sistema

📦 Componentes Principales

1. chatbot-gemini (Backend)

2. kebab-chatbot-ai (Frontend)

🚀 Instalación y Configuración

Prerrequisitos

Variables de Entorno

chatbot-gemini/.env

kebab-chatbot-ai/.env.local

🐳 Instalación con Docker (Recomendado)

💻 Instalación Local (Desarrollo)

Backend (chatbot-gemini)

Frontend (kebab-chatbot-ai)

📊 Base de Datos (Supabase PostgreSQL)

Tablas Principales

Sincronización en Tiempo Real

Row Level Security (RLS)

🤖 Flujo del Chatbot con IA

Proceso de Conversación

Function Calling (Gemini AI)

Características de la IA

🖥️ Dashboard - Funcionalidades

📈 Dashboard Principal

📦 Gestión de Pedidos (Sincronización Central)

💬 Chat

🍽️ Catálogo

⚙️ Configuración

📱 WhatsApp

🔌 API del Backend

Endpoints Principales

Gestión de Sesiones WhatsApp

Envío de Mensajes

Health Check

WebSockets (Socket.io)

🔐 Autenticación y Seguridad

Supabase Auth

Row Level Security (RLS)

Docker Security

🛠️ Tecnologías Utilizadas

Backend

Frontend

DevOps

📁 Estructura de Directorios Detallada

Backend (chatbot-gemini)

Frontend (kebab-chatbot-ai)

🧪 Testing y Desarrollo

Modo Desarrollo

Backend

Frontend

Build de Producción

Linting

🚢 Despliegue

Despliegue en Producción

Producción Actual

Docker Compose

Comandos Útiles

Variables de Entorno en Producción

🐛 Troubleshooting

El bot de WhatsApp no conecta

Error de CORS en el frontend

Base de datos: errores de permisos

Mensajes no se procesan

📝 Roadmap y Próximas Mejoras

🎯 Prioridad Alta - Mejoras de Sincronización

📊 Analytics y Reportes

💰 Pagos y Entregas

📱 Multicanal

🎁 Fidelización y CRM

🏪 Gestión Avanzada

🤝 Contribución

Guía de Estilo

Flujo de Trabajo