Arquitectura de plataforma - ZappWay - Connect custom data to large language models

Lo que aprenderás: Esta página es la referencia de arquitectura autorizada para ZappWay, generada a partir de un escaneo completo del código base (commit 14982f37). Cubre todos los subsistemas principales: estructura monorepo, esquema de base de datos, topología de cola/trabajador, cargadores de ingestión, capa vectorial Qdrant, canalización de incrustación, RAG multidisparo adaptable, motor de chat, autenticación, orquestador de sincronización, las integraciones de 13 canales, almacenamiento de archivos, enrutador modelo LLM y observabilidad.

1. Arquitectura general del sistema

ZappWay es un pnpm monorepo estructurado en 3 aplicaciones y 2 árboles de paquetes. La aplicación apps/zappway aloja el panel, la página de destino, el blog y los documentos. Toda la lógica empresarial central se encuentra en packages/zappway/lib (~160 archivos). Una aplicación apps/workers-services dedicada ejecuta todos los trabajadores en segundo plano y la API de WhatsApp Bridge de forma aislada, consumiendo trabajos de las colas BullMQ-Pro respaldadas por Redis.

Mapa de aplicación

Aplicación	Camino	Marco	Propósito
Panel de control	`apps/zappway/dashboard`	Siguiente.js	Interfaz de usuario principal de SaaS
Blog	`apps/zappway/blog`	Siguiente.js	Blog de marketing
Documentos	`apps/zappway/docs`	Basado en MDX	Documentación del producto
Página de destino	`apps/zappway/lp`	Siguiente.js	Página de destino
Servicios para trabajadores	`apps/workers-services`	Siguiente.js	Trabajadores de fondo + Puente WA
ZappFlux	`apps/zappflux`	Siguiente.js	Producto secundario (BD compartida)

Mapa del paquete

Paquete	Camino	Propósito
`@zappway/prisma`	`packages/zappway/prisma`	Exportaciones de esquema, cliente y navegador de Prisma
`@zappway/lib`	`packages/zappway/lib`	Lógica empresarial central (~160 archivos)
`@zappway/integrations`	`packages/zappway/integrations`	Adaptadores de 13 canales
`@zappway/ui`	`packages/zappway/ui`	Componentes compartidos de React

2. Capa de base de datos

Fuente: packages/zappway/prisma/schema.prisma (1548 líneas) · 33 modelos · 23 enumeraciones PostgreSQL a través de Prisma con las funciones de vista previa fullTextSearch y fullTextIndex habilitadas. El modelo Organization es el límite del inquilino raíz; todas las demás entidades tienen su alcance directa o transitivamente.

Inventario de modelo completo

#	Modelo	Clave de inquilino	Propósito
1	`User`	—	Cuenta de usuario de la plataforma
2	`Organization`	`id` (raíz)	Contenedor de inquilino
3	`Membership`	`organizationId`	Relación usuario-organización (RBAC)
4	`ApiKey`	`organizationId`	Acceso programático
5	`Usage`	`organizationId`	Seguimiento del uso de facturación
6	`Agent`	`organizationId`	Definición AI Employee
7	`Datastore`	`organizationId`	Contenedor de base de conocimientos
8	`AppDatasource`	`organizationId`	Fuente de datos individuales
9	`Conversation`	`organizationId`	Sesión de charla
10	`Message`	vía conversación	Mensaje individual
11	`Tool`	vía Agente	Definición de herramienta agente
12	`Form`	vía Agente	Forma dinámica
13	`FormSubmission`	vía formulario	Formulario de respuesta
14	`Contact`	`organizationId`	Contacto CRM
15	`Subscription`	`organizationId`	Plan de facturación
16	`Product`	—	Producto de rayas
17	`Price`	—	Precio de la raya
18	`Account`	`userId`	Enlace del proveedor de OAuth
19	`Session`	`organizationId`	Sesión de autenticación
20	`VerificationToken`	—	Verificación por correo electrónico
21	`ServiceProvider`	`organizationId`	Credenciales de integración
22	`ActionApproval`	vía conversación	Solicitud de aprobación de herramienta
23	`Attachment`	vía mensaje	Archivo adjunto de mensaje
24	`ExternalIntegration`	vía Agente	Webhook/configuración externa
25	`LLMTaskOutput`	`organizationId`	Resultado de la tarea asincrónica LLM
26	`MailInbox`	`organizationId`	Configuración de la bandeja de entrada de correo electrónico
27	`ConversationCrmTag`	`organizationId`	Etiquetado CRM
28	`Lead`	`organizationId`	Captura de clientes potenciales
29	`XPBNPEval`	—	Evaluación de prueba A/B
30	`AgentsOnDatastores`	—	Unión agente M:N-almacén de datos
31	`Coupon`	—	Cupón de facturación
32	`UserApiKey`	`userId`	Clave API a nivel de usuario
33	`CrmLog`	`organizationId`	Registro de actividad de CRM

Enumeraciones clave

Enumeración	Valores de muestra
`DatasourceType`	`web_page`, `web_site`, `text`, `file`, `google_drive_file`, `notion`, `youtube_video`, `youtube_bulk`, `qa`, `api`
`DatasourceStatus`	`unsynched`, `pending`, `running`, `synched`, `error`, `usage_limit_reached`, `stalled`
`ConversationChannel`	`dashboard`, `website`, `whatsapp`, `telegram`, `slack`, `crisp`, `form`, `mail`, `api`, `zapier`, `zendesk`, `messenger`, `instagram`
`AgentModelName`	Más de 50 valores de enumeración de modelos: consulte la Sección 13
`SubscriptionPlan`	`level_0`, `level_1`, `level_2`, `level_3`, `level_4`
`MembershipRole`	`OWNER`, `ADMIN`, `USER`
`GlobalRole`	`SUPERADMIN`, `CUSTOMER`
`ToolType`	`datastore`, `http`, `form`, `mark_as_resolved`, `request_human`, `lead_capture`, `payment`

3. Arquitectura de colas y trabajadores

Fuente: packages/zappway/lib/types/index.ts, apps/workers-services/workers/ Tres colas BullMQ-Pro dedicadas separan las preocupaciones. La cola load-datasource es la cola activa principal; los otros dos están parcialmente implementados.

Configuración del trabajador: cargador de fuente de datos

Configuración	Valor	Anulación de entorno
Nombre de la cola	`load-datasource`	—
Concurrencia	3	`DS_WORKER_CONCURRENCY`
Duración del bloqueo	8 minutos	`DS_BULL_LOCK_DURATION_MS`
Intervalo estancado	años 90	`DS_BULL_STALLED_INTERVAL_MS`
Recuento máximo estancado	2	`DS_BULL_MAX_STALLED_COUNT`
Bloqueo de deduplicación TTL	10 minutos	`DS_JOB_LOCK_TTL_MS`
Eliminar al completar	Últimos 1000	—
Eliminar en caso de error	Últimos 5000	—

Mecanismo de deduplicación: Redis SET NX con la clave ld:lock:{datasourceId} evita que la misma fuente de datos se ejecute en paralelo. Apagado elegante: maneja SIGTERM y SIGINT: cierra el trabajador y sale de Redis limpiamente.

Inventario de trabajadores

Trabajador	Cola	Estado
`datasource-loader.ts`	`load-datasource`	✅ Activo
`check-and-sync-cron.ts`	basado en cron	✅ Activo
`generate-rag.ts`	`generate-rag-document`	✅ Activo
`index-media-memory.ts`	`index-media-memory`	✅ Activo
`check-stalled.ts`	interno	✅ Activo
`trial-expiry-check.ts`	basado en cron	✅ Activo
`usage-reconciler.ts`	basado en cron	✅ Activo
`scheduler.ts`	orquestador	✅ Activo

4. Motor de ingesta y cargadores

Fuente: packages/zappway/lib/datastores/datasources/, packages/zappway/lib/loaders/ Todos los cargadores extienden DatasourceLoaderBase. El punto de entrada taskLoadDatasource() selecciona el cargador correcto en tiempo de ejecución según DatasourceType. La salida es una matriz AppDocument[] normalizada que se introduce en el motor de fragmentación y luego en Qdrant.

Mapeo del cargador

Tipo de fuente de datos	Cargador	Fuente
`web_page`	`WebPageLoader`	Recuperación de URL
`web_site`	`WebSiteLoader`	Mapa del sitio / rastreo
`file`	`FileLoader`	Carga S3
`text`	`TextLoader`	Entrada de texto sin formato
`qa`	`QALoader`	Pares de preguntas y respuestas
`youtube_video`	`YouTubeLoader`	API de YouTube
`youtube_bulk`	`YouTubeLoader`	Vídeo múltiple
`google_drive_file`	`GoogleDriveLoader`	API de unidad
`google_drive_folder`	`GoogleDriveLoader`	API de unidad
`notion`	`NotionLoader`	API de nociones
`notion_page`	`NotionLoader`	API de nociones
`api`	`APILoader`	Punto final HTTP

Cargador de sitios web: detalle de canalización

Fuente: packages/zappway/lib/loaders/web-site.ts (515 líneas) El WebSiteLoader es el cargador más complejo. Su proceso se ejecuta en 6 etapas: (1) Descubrimiento: analiza el XML del mapa del sitio o rastrea a través de findDomainPages(); (2) Normalización: desduplicación de URL, eliminación de parámetros UTM, nombre de host en minúsculas; (3) Filtrado de lista negra: aplica la configuración black_listed_urls; (4) Sondeo HTTP — HEAD → GET con reparación de ruta de servidor en 404; (5) Administración de niños: inserta web_page fuentes de datos infantiles, elimina huérfanos; (6) En cola: emite trabajos secundarios con puntuaciones de prioridad (inicio = 5, mapa del sitio = 8, otros = 10). La simultaneidad tiene un límite de 6 a través de mapWithConcurrency. Límite del plan aplicado a través de accountConfig[plan].limits.maxWebsiteURL (predeterminado: 25).

5. Capa de base de datos vectorial — Qdrant

Fuente: packages/zappway/lib/datastores/qdrant.ts (731 líneas) Cada almacén de datos se asigna exactamente a una colección de Qdrant denominada zw_{datastoreId}, lo que proporciona un aislamiento vectorial estricto por inquilino. QdrantManager incluye una rutina de migración automática que detecta discrepancias en las métricas de dimensión o distancia y recrea la colección de forma transparente, lo que permite actualizaciones del modelo de incorporación sin tiempo de inactividad.

Configuración de colección

Parámetro	Valor
Tamaño del vector	3072
Métrica de distancia	Coseno
Nombre de la colección	`zw_{datastoreId}`
HNSW `m`	16
HNSW `ef_construct`	100
Cuantización	Escalar Int8: percentil 99
Carga útil en disco	`true`
Coherencia de escritura	`majority`

Esquema de carga útil (por punto)

Campo	Tipo	Propósito
`datastore_id`	cadena	Almacén de datos con ámbito de inquilino
`datasource_id`	cadena	Documento fuente
`datasource_hash`	cadena	Hash de contenido para deduplicación
`chunk_hash`	cadena	Hachís en trozos individuales
`chunk_offset`	entero	Posición en el documento
`text`	cadena	Contenido del texto original
`tags`	cadena[]	Etiquetas definidas por el usuario
`custom_id`	cadena	Referencia externa
`page_number`	entero	Número de página PDF
`total_pages`	entero	Total de páginas PDF

6. Incrustación de canalización

Fuente: packages/zappway/lib/datastores/gemini-embeddings.ts, packages/zappway/lib/multimodal-memory/ Todas las incrustaciones utilizan Gemini Embedding 2 Preview, lo que produce vectores de 3072 dimensiones que coinciden con el VECTOR_SIZE de Qdrant. La canalización utiliza valores taskType asimétricos por sitio de llamada (RETRIEVAL_DOCUMENT durante la ingestión y RETRIEVAL_QUERY en el momento de la búsqueda), lo cual es fundamental para la calidad de la recuperación con el modelo de incrustación asimétrico de Gemini.

Configuración

Parámetro	Valor
Modelo	`gemini-embedding-2-preview`
Dimensiones de salida	3072
Tamaño del lote	100 (límite de API por `batchEmbedContents`)
Autenticación	`x-goog-api-key` — env `GOOGLE_AI_API_KEY`

Soporte multimodal

embedMultimodal() acepta GeminiPart[][] donde cada parte puede ser { text } o { inlineData: { mimeType, data } } (imágenes codificadas en base64, fotogramas de vídeo, audio, páginas PDF). Esto incorpora contenido que no es texto en el mismo espacio de 3072 dimensiones que el texto, lo que permite una verdadera búsqueda semántica multimodal. El módulo multimodal-memory/ proporciona indexación dedicada (indexer.ts - 24,5 KB), fragmentos específicos de medios (media-chunkers.ts), gestión de colecciones, búsqueda y activadores de colas asíncronas.

7. RAG y canalización de recuperación

Fuente: packages/zappway/lib/chat-v4/rag.ts (493 líneas) ZappWay implementa RAG adaptativo multidisparo con hasta 6 intentos de recuperación progresivos en 3 niveles de calidad. Cada intento relaja los umbrales de similitud para maximizar el recuerdo, mientras que evaluateRagQuality() permite la salida anticipada cuando los resultados son lo suficientemente sólidos. Un disyuntor evita fallas en cascada y ragMemo (caché en memoria) deduplica intentos idénticos dentro de una sesión.

Umbrales adaptativos

Intento	Etiqueta	Modo profundo	Normales	TopK
1	`strict`	0,55	0,48	30
2	`balanced-high`	0,48	0,42	45
3	`balanced`	0,42	0,38	60
4	`balanced-low`	0,37	0,32	75
5	`relaxed`	0,33	0,28	90
6	`permissive`	0,30	0,25	100

El Modo profundo se activa mediante shouldFavorDeepRag(query) y aplica umbrales iniciales más altos. minUcount es 1 para consultas de un solo almacén de datos y 2 para consultas de varios almacenes de datos. Los tiempos de espera varían de 8 segundos (Nivel 1) a 12 segundos (Nivel 3), limitados por el presupuesto restante del chat. Si es remainingMs() < 120s, el máximo de intentos se reduce a 4.

8. Motor de chat y conversación

Fuente: packages/zappway/lib/chat-v4/chat.ts (1147 líneas), packages/zappway/lib/agent/tools/ La función de chat organiza el ensamblaje de avisos del sistema, el truncamiento del historial de mensajes, el RAG de múltiples disparos, la creación de herramientas de tiempo de ejecución, la ejecución de LLM con transmisión y la cadena de respaldo del modelo completo, todo dentro de un presupuesto de tiempo compartido que se aplica en cada punto de control.

Tipos de eventos SSE

Evento	Propósito
`answer`	Delta de texto transmitido
`tool_call`	Notificación de invocación de herramienta
`endpoint_response`	Datos de respuesta de la herramienta HTTP
`step`	Indicador de paso de procesamiento
`metadata`	Uso del modelo, fuentes, ventana contextual
`error`	Notificación de errores
`done`	Señal de finalización de flujo

Herramientas de tiempo de ejecución

Archivo de herramientas	Tipo de herramienta	Propósito
`datastore.ts`	`datastore`	RAG dinámico dentro del bucle de herramientas
`form.ts`	`form`	Presentar y recopilar formularios dinámicos
`http.ts`	`http`	Llamar a API externas
`request-human.ts`	`request_human`	Transferencia a agente humano
`lead-capture.ts`	`lead_capture`	Capture información del visitante
`payment.ts`	`payment`	Iniciar flujo de pago
`mark-as-resolved.ts`	`mark_as_resolved`	Cerrar ticket de soporte
`ui.ts`	Representación de la interfaz de usuario	Componentes de interfaz de usuario personalizados

9. Aislamiento y autenticación de múltiples inquilinos

Fuentes: packages/zappway/lib/auth/authConfig.ts, authAdapter.ts y authProviders.ts Auth.js Core procesa directamente las solicitudes HTTP del servidor con un adaptador Prisma personalizado; next-auth/react permanece limitado al cliente. Se admiten cuatro métodos de inicio de sesión. En el primer inicio de sesión, la plataforma aprovisiona automáticamente la pila completa de inquilinos de forma atómica.

Aislamiento de inquilinos por capa

Capa	Mecanismo
Base de datos	`organizationId` en cada modelo de inquilino
API	El middleware de sesión inyecta `organization` de la sesión
Base de datos vectorial	Una colección de Qdrant por almacén de datos (`zw_{datastoreId}`)
Almacenamiento de archivos	Prefijo S3 `organizations/{orgId}/`
Colas	`organizationId` se lleva en cada carga útil de trabajo

Modelo RBAC

Rol	Alcance	Acceso
`SUPERADMIN`	Mundial	Sistema completo
`CUSTOMER`	Mundial	Usuario estándar
`OWNER`	Organización	Gestión completa de la organización
`ADMIN`	Organización	Administrar agentes y almacenes de datos
`USER`	Organización	Sólo lectura

Configuración de sesión

Configuración	Producción	Desarrollo
Estrategia	`database`	`database`
Nombre de la cookie	`__Secure-authjs.session-token`	`authjs.session-token`
Dominio de cookies	`.{rootDomain}`	`undefined`
Seguro	`true`	`false`

Compatibilidad regional: 37 configuraciones regionales, incluido RTL (árabe, hebreo, persa, urdu). Orden de resolución: ruta URL → NEXT_LOCALE cookie → i18next cookie → Accept-Language encabezado → predeterminado en.

10. Orquestador de sincronización

Fuente: apps/workers-services/workers/check-and-sync-cron.ts Un trabajador controlado por cron escanea todas las fuentes de datos con status = synched, filtra por lastSyncAt + syncInterval y distribuye trabajos individuales load-datasource. Un trabajador check-stalled maneja la recuperación de fuentes de datos atascadas en el estado running más allá de un umbral configurable.

11. Integraciones y canales externos

Fuente: packages/zappway/integrations/ — Adaptadores de 13 canales Todos los canales normalizan los mensajes entrantes al mismo modelo interno Conversation + Message y enrutan a través del motor unificado chat-v4.

Capacidades del canal

Canal	Dirección	Transmisión	Soporte de formulario
`dashboard`	Bidireccional	ESS	Sí
`website`	Bidireccional	ESS	Sí
`whatsapp`	Bidireccional	No (webhook)	Limitado
`telegram`	Bidireccional	No (webhook)	Limitado
`slack`	Bidireccional	No (webhook)	No
`crisp`	Bidireccional	No (webhook)	No
`mail`	Asíncrono	No	No
`api`	Solicitud/Respuesta	Opcional	No
`zapier`	Gancho web	No	No
`form`	Envío de formulario	No	Sí
`zendesk`	Bidireccional	No (webhook)	No
`messenger`	Bidireccional	No (webhook)	No
`instagram`	Bidireccional	No (webhook)	No

Autenticación del proveedor de servicios

Tipo	Mecanismo de autenticación
`website`	Clave API
`whatsapp`	Token de API de nube
`telegram`	Ficha de robot
`slack`	OAuth
`crisp`	Clave API + ID del sitio web
`zendesk`	Token API
`messenger` / `instagram`	Token de acceso a la página
`notion`	Token de integración
`google_drive`	Token de actualización de OAuth
`zapier`	URL de webhook

12. Almacenamiento de archivos y canalización de medios

Fuente: packages/zappway/lib/aws.ts Admite almacenamiento compatible con S3 (AWS S3, Cloudflare R2, MinIO) a través de AWS SDK v3. Los archivos se cargan a través de URL prefirmadas, se almacenan en organizations/{orgId}/ y FileLoader los extrae para su extracción e ingesta.

Variables de entorno S3

Variables	Propósito
`APP_AWS_REGION`	Región de AWS
`APP_AWS_ACCESS_KEY`	ID de clave de acceso
`APP_AWS_SECRET_KEY`	Clave de acceso secreta
`APP_AWS_S3_ENDPOINT`	Punto final personalizado (R2/MinIO)
`APP_AWS_S3_FORCE_PATH_STYLE`	Estilo de ruta para R2/MinIO
`APP_AWS_S3_BUCKET`	Cubo objetivo

13. Orquestación LLM y enrutador de modelos

Fuente: packages/zappway/lib/config.ts (943 líneas), packages/zappway/lib/chat-model/model.ts (745 líneas) 50+ models across 12 providers via a unified OpenAI-SDK-compatible interface. Provider routing is automatic based on each model’s baseUrl in ModelConfig. OpenAI, Google Gemini, and OpenRouter are all accessed through the same OpenAI SDK client with different base URLs and API keys.

Inventario de modelos

🧠 OpenAI - Directo

Modelo	Fichas máximas	Costo
GPT-4o / GPT-4o Mini	128K	15/4
GPT-5 / Mini / Nano	400K	15/5/4
Charla GPT-5.1 / 5.1	400K	15 / 12
GPT-5.2 / Chat 5.2 / Chat 5.2 Más reciente	400K	20 / 15 / 15
Chat GPT-5.3 más reciente / Códice 5.3	400K/128K	15
GPT-5.4 / 5.4 Mini / 5.4 Nano	400K	15/6/5

🟡 Google: directo a través de la API de Gemini

Modelo	Fichas máximas	Costo
Géminis Flash 2.0 / 2.5	1 millón	5/10
Géminis Pro 2.5	1 millón	12
Géminis 3 Pro / 3 Flash	1 millón	15/10
Imagen profesional de Géminis 3	64K	15
Géminis 3.1 Flash Lite / Imagen Flash / Pro	1M / 64K / 1M	5/8/15

🔶 Antrópico - vía OpenRouter

Modelo	Fichas máximas	Costo
Claude 3.5 Haiku / 3.5 Soneto	200K	12/15
Soneto de Claude 4	200K	15
Claude 4.5 Haiku / 4.5 Soneto	200K	12/15
Claude Opus 4.5 / Opus 4.6 / Soneto 4.6	200K	20/20/15

Otros proveedores: a través de OpenRouter

Modelo	Proveedor	Costo
DeepSeek V3.2 / R1	Búsqueda profunda	5/8
Llama-4 Maverick / Explorador	Meta	10/5
Mistral Grande 2512 / 8x22B / 8x7B / Pequeño Creativo	Mistral	5/5/2/2
Sónar Pro	Perplejidad	15
Grok 4 / 4.1 Rápido	xAI	15/5
Nova Premier/Nova 2 Lite	Amazonas	12/6
LFM2 8B / LFM2 24B	Líquido	1/1
MiniMax M2.7	MiniMax	5
MiMo-V2-Omni / MiMo-V2-Pro	Xiaomi	6/10

Modelos de nivel gratuito: gpt_4o_mini, gpt_5_mini, gpt_5_nano, gpt_5_4_mini, gpt_5_4_nano, gemini_flash_2_0

Importante: Los modelos de la familia GPT-5 no admiten el ajuste manual de temperatura; utilizan el reconocimiento automático de temperatura.

14. Observabilidad y seguimiento

Fuente: packages/zappway/lib/logger.ts, apps/workers-services/sentry.*.config.ts

Componente	Tecnología	Estado
Registrador de núcleos	Pino	✅ Activo
Bonita impresión	pino-bonita	✅ Activo
Nube de axioma	@axiomhq/pino	❌ Comentado
Registrador de chat	Pino niño `logChat`	✅ Activo
Seguimiento de errores	Sentry (cliente + servidor + borde)	✅ Activo

Los trabajadores publican una carga útil WorkerHealth en Redis (health:worker:{name}, 30s TTL) cada 10s. Campos: status, startedAt, lastActivityAt, jobsProcessed, jobsFailed, queueLength, system.memoryMB, system.uptimeMs. Expuesto a través de /api/workers/health. Los trabajadores también transmiten registros en tiempo real al canal Redis Pub/Sub logs:datasource para monitoreo en vivo del panel.

15. Lagunas y recomendaciones

Brechas identificadas

#	Área	Brecha	Gravedad
1	Observabilidad	Integración de Axiom comentada: sin registro en la nube en producción	🟡 Medio
2	Limitación de tasa	No hay límite de velocidad visible en los puntos finales de la API de chat	🔴 Alto
3	Cola DLQ	Sin cola de mensajes fallidos para trabajos fallidos permanentemente	🟡 Medio
4	Incrustación de respaldo	Proveedor de integración único (Gemini): no hay respaldo si la API no funciona	🟡 Medio
5	Copia de seguridad de base de datos vectorial	No hay una estrategia de copia de seguridad/instantánea de Qdrant documentada	🟡 Medio
6	Cobertura de prueba	No se encontraron archivos de prueba en los directorios escaneados	🔴 Alto

Recomendaciones

Enable cloud logging — Uncomment Axiom or use Datadog / Grafana Loki for production log retention.
Add rate limiting — Per-organization token-bucket on chat endpoints.
Implement DLQ — BullMQ supports deadLetterQueue option; enable for all 3 queues.
Embedding fallback — text-embedding-3-large from OpenAI (3072-dim compatible) as secondary.
Qdrant snapshots — Cron-based snapshot to S3 for disaster recovery.
Test coverage — Integration tests for the RAG pipeline and ingestion workers as a starting priority.

Fortalezas arquitectónicas

Fuerza	Detalle
RAG multidisparo	Recuperación adaptativa de 6 intentos con evaluación de calidad y disyuntor
Migración automática	Colección Qdrant recreada de forma transparente mediante el cambio de modelo integrado
Apagado elegante	Todos los trabajadores manejan `SIGTERM` / `SIGINT` limpiamente
Cerraduras de desduplicación	Redis `SET NX` evita el procesamiento paralelo de la misma fuente de datos
Gestión Presupuestaria	Presupuesto de tiempo aplicado en cada punto de control del canal de chat
Más de 50 modelos	Interfaz unificada OpenAI-SDK en 12 proveedores
Verdadero multimodal	Inserción, fragmentación y búsqueda multimodal de extremo a extremo de imágenes, audio y vídeo
Aislamiento total de inquilinos	Separar colecciones Qdrant y prefijos S3 por organización

Vocabulario

Término	Descripción
Almacén de datos	Contenedor de fuentes de datos: se asigna a una colección Qdrant (`zw_{datastoreId}`)
Fuente de datos	Fuente de datos individual: `web_page`, `file`, `youtube_video`, etc.
Documento de aplicación	Salida de formato de documento normalizado por todos los cargadores
TRAPO multidisparo	Recuperación adaptativa con hasta 6 intentos progresivos en 3 niveles de calidad
Disyuntor	Detiene RAG después de 3 fallas consecutivas durante 60 segundos para evitar errores en cascada
Modo profundo	Modo RAG de umbral alto activado por `shouldFavorDeepRag(query)`
BullMQ-Pro	Cola de trabajos respaldada por Redis con funciones avanzadas de programación y flujo
Qdrante	Base de datos vectorial utilizada para búsqueda semántica multimodal
Incrustación de Géminis 2	Modelo de incrustación multimodal que produce vectores de 3072 dimensiones
Tipo de tarea	Modo de incrustación asimétrica: `RETRIEVAL_DOCUMENT` para ingestión, `RETRIEVAL_QUERY` para búsqueda
AgentsOnDatastores	Tabla de unión M:N que vincula agentes con almacenes de datos
HNSW	Mundo pequeño navegable jerárquico: índice aproximado del vecino más cercano en Qdrant

· Última actualización: marzo de 2026

​🔢 Tabla de contenidos

​1. Arquitectura general del sistema

​Mapa de aplicación

​Mapa del paquete

​2. Capa de base de datos

​Inventario de modelo completo

​Enumeraciones clave

​3. Arquitectura de colas y trabajadores

​Configuración del trabajador: cargador de fuente de datos

​Inventario de trabajadores

​4. Motor de ingesta y cargadores

​Mapeo del cargador

​Cargador de sitios web: detalle de canalización

​5. Capa de base de datos vectorial — Qdrant

​Configuración de colección

​Esquema de carga útil (por punto)

​6. Incrustación de canalización

​Configuración

​Soporte multimodal

​7. RAG y canalización de recuperación

​Umbrales adaptativos

​8. Motor de chat y conversación

​Tipos de eventos SSE

​Herramientas de tiempo de ejecución

​9. Aislamiento y autenticación de múltiples inquilinos

​Aislamiento de inquilinos por capa

​Modelo RBAC

​Configuración de sesión

​10. Orquestador de sincronización

​11. Integraciones y canales externos

​Capacidades del canal

​Autenticación del proveedor de servicios

​12. Almacenamiento de archivos y canalización de medios

​Variables de entorno S3

​13. Orquestación LLM y enrutador de modelos

​Inventario de modelos

​🧠 OpenAI - Directo

​🟡 Google: directo a través de la API de Gemini

​🔶 Antrópico - vía OpenRouter

​Otros proveedores: a través de OpenRouter

​14. Observabilidad y seguimiento

​15. Lagunas y recomendaciones

​Brechas identificadas

​Recomendaciones

​Fortalezas arquitectónicas

​Vocabulario