Synaplan Multimodal Gateway

Synaplan

Gestión del conocimiento impulsada por IA con RAG, widgets de chat e integración multicanal.

Instancia en vivo: web.synaplan.com  |  Documentación: docs.synaplan.com  |  API: Swagger UI

---

Requisitos previos

• Docker + Docker Compose v2 (Docker Desktop en macOS/Windows, o Docker Engine + el plugin Compose en Linux)
• Git
• 8 GB de RAM mínimo (16 GB recomendados para la instalación estándar con IA local)
• ~9 GB de espacio libre en disco para la instalación estándar (~5 GB para la mínima)
• Puertos TCP libres 5173, 8000, 8082, 8025, 3307, 6333, 11435

Macs con Apple Silicon (M1–M4): Las imágenes de contenedor de Synaplan se publican para linux/amd64, por lo que se ejecutan bajo emulación en Apple Silicon. En Docker Desktop → Configuración → General, habilita "Usar Rosetta para emulación x86/amd64 en Apple Silicon" (macOS 13+) para contenedores mucho más rápidos y estables que con QEMU por defecto. Todo funciona sin ello — solo que más lento, y la primera compilación tarda más.

Inicio rápido

git clone https://github.com/metadist/synaplan.git
cd synaplan
docker compose up -d

Abre http://localhost:5173 — la interfaz de usuario estará lista en ~2 minutos. Con la instalación estándar, los modelos locales de Ollama (gpt-oss:20b, bge-m3, ~14 GB en total) continúan descargándose en segundo plano — el chat que usa IA local comenzará a funcionar una vez que finalice esa descarga (docker compose logs -f backend muestra el progreso). Para una primera experiencia más rápida, usa la instalación Mínima a continuación.

---

Opciones de instalación

Modo	Comando	Tamaño	Ideal para
Estándar	docker compose up -d	~9 GB	Funciones completas, IA local
Mínima	docker compose -f docker-compose-minimal.yml up -d	~5 GB	Solo IA en la nube (Groq/OpenAI)

Para la instalación mínima, configura tu clave API antes de iniciar el stack para que el primer arranque ya la detecte (evita un reinicio). Obtén una clave gratuita en console.groq.com:

echo "GROQ_API_KEY=your_key" >> backend/.env
docker compose -f docker-compose-minimal.yml up -d

¿Ya lo iniciaste sin una clave? Agrégala y reinicia el backend:

echo "GROQ_API_KEY=your_key" >> backend/.env && docker compose restart backend

---

Acceso

Servicio	URL
App	http://localhost:5173
API	http://localhost:8000
Documentación de API	http://localhost:8000/api/doc
phpMyAdmin	http://localhost:8082
MailHog	http://localhost:8025

Credenciales de inicio de sesión predeterminadas:

Correo electrónico	Contraseña	Nivel
[email protected]	admin123	ADMIN
[email protected]	demo123	PRO
[email protected]	test123	NUEVO (sin verificar)

---

Características

• Chat con IA — Ollama, OpenAI, Anthropic, Groq, Gemini
• Enrutamiento multitarea — Un planificador de IA descompone solicitudes complejas en un grafo de tareas (extraer → resumir → generar → responder) y transmite tarjetas de tareas en vivo mientras se ejecutan los pasos
• Búsqueda RAG — Búsqueda semántica de documentos con MariaDB VECTOR o Qdrant
• Widget de chat — Incrustar en cualquier sitio web (guía del widget)
• Soporte en vivo — Capa WebSocket en tiempo real (Centrifugo + Redis): toma de control humana de chats del widget, indicadores de escritura, notificaciones al operador (guía de tiempo real)
• WhatsApp — Integración con la API de Meta Business
• Correo electrónico — Respuestas de correo electrónico impulsadas por IA
• Audio — Transcripción con Whisper (entrada) + synaplan-tts opcional (salida)
• Documentos — PDF, Word, Excel, imágenes con OCR
• Memorias de IA — Perfilado de usuarios con búsqueda vectorial Qdrant
• Sistema de retroalimentación — Captura y análisis de retroalimentación impulsados por Qdrant
• Plugins — Sistema de plugins no invasivo (guía de plugins)
• Servidor MCP (acceso anticipado) — Conecta clientes de IA (Claude, Cursor, …) a través del Protocolo de Contexto de Modelo; tu RAG y memorias se convierten en herramientas en POST /mcp (guía MCP)
• Cliente MCP (acceso anticipado) — Conecta tus servidores MCP (CRM, wiki, n8n, …) en Canales → Servidores MCP; el planificador multitarea extrae datos en vivo de ellos a través de nodos DAG mcp_fetch — solo lectura, protegido contra SSRF, participación por tema. Habilitado por los flags BCONFIG sembrados (MCP.CLIENT_ENABLED, MULTITASK.MCP_FETCH_ENABLED — app:seed los activa al desplegar; una fila explícita 0 es el interruptor de apagado del operador). Consulta docs/MULTITASK_DATA_NODES.md

---

Base de datos vectorial Qdrant

Qdrant se ejecuta como un servicio interno de Docker — no se necesita configuración. Impulsa las memorias de IA, la búsqueda de documentos RAG y el sistema de retroalimentación.

Se inicia automáticamente con docker compose up -d. Synaplan funciona completamente sin él (las memorias y la búsqueda vectorial estarán deshabilitadas).

---

Procesamiento en tiempo real y en segundo plano

Ambos archivos compose también inician tres servicios internos (sin puertos de host, sin configuración necesaria):

Servicio	Rol
redis	Infraestructura compartida obligatoria: caché, sesiones, bloqueos, límites de velocidad, colas de mensajes (Redis Streams), motor Centrifugo
centrifugo	Puerta de enlace WebSocket para funciones en tiempo real (toma de control de chat en vivo, indicadores de escritura, notificaciones al operador) — los navegadores se conectan desde el mismo origen a través de /connection/websocket
worker	Consumidor de Symfony Messenger que ejecuta trabajos asíncronos (procesamiento de IA, indexación de documentos, rastreo de widgets)

En un clúster multinodo, todos los nodos comparten un Redis, por lo que los eventos WebSocket publicados en un nodo llegan a los navegadores conectados a cualquier otro. Detalles: docs/REALTIME.md.

---

Texto a voz (opcional)

Para salida de voz, ejecuta synaplan-tts junto a Synaplan:

git clone https://github.com/metadist/synaplan-tts.git && cd synaplan-tts && docker compose up -d

---

Comandos comunes

# Logs
docker compose logs -f backend

# Restart
docker compose restart backend

# Reset database
docker compose down -v && docker compose up -d

# Run tests
make test

# Code quality
make lint

---

Documentación

La documentación para usuarios y de la API se encuentra en docs.synaplan.com. Fuente: metadist/synaplan-docs.

Guías dentro del repositorio (para desarrolladores que trabajan en este código):

Guía	Descripción
Instalación	Instrucciones detalladas de configuración
Configuración	Variables de entorno, claves API
Desarrollo	Comandos, pruebas, arquitectura
Tiempo real / WebSockets	Capa de tiempo real Centrifugo + Redis, despliegue multinodo
Sistema RAG	Búsqueda y procesamiento de documentos
Widget de chat	Incrustar chat en sitios web
WhatsApp	Configuración de la API de Meta Business
Correo electrónico	Integración del canal de correo electrónico

Repositorios relacionados

Repositorio	Propósito
synaplan	Aplicación principal (este repositorio)
synaplan-docs	Sitio de documentación pública (docs.synaplan.com)
synaplan-tts	Servicio TTS Piper opcional
synaplan-sortx	Plugin de ordenación de documentos + herramienta local
synaplan-charts	Charts Helm para Kubernetes
synaplan-platform	Configuraciones de despliegue en producción

---

Estructura del proyecto

synaplan/
├── backend/        # Symfony PHP API
├── frontend/       # Vue.js SPA
├── docs/           # Documentation
├── _docker/        # Docker configs
└── plugins/        # Plugin system

---

Contribuir

Consulta AGENTS.md para las pautas de desarrollo y estándares de código.

---

Licencia

Apache-2.0