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

O que você aprenderá: Esta página é a referência de arquitetura oficial para ZappWay, gerada a partir de uma varredura completa da base de código (commit 14982f37). Ele cobre todos os principais subsistemas: a estrutura monorepo, esquema de banco de dados, topologia de fila/trabalhador, carregadores de ingestão, camada vetorial Qdrant, pipeline de incorporação, RAG multi-shot adaptativo, mecanismo de chat, autenticação, orquestrador de sincronização, todas as integrações de 13 canais, armazenamento de arquivos, roteador de modelo LLM e observabilidade.

1. Arquitetura geral do sistema

ZappWay é um pnpm monorepo estruturado em 3 aplicativos e 2 árvores de pacotes. O aplicativo apps/zappway hospeda o Dashboard, Landing, Blog e Docs. Toda a lógica de negócios principal reside em packages/zappway/lib (cerca de 160 arquivos). Um aplicativo apps/workers-services dedicado executa todos os trabalhadores em segundo plano e a API WhatsApp Bridge isoladamente, consumindo trabalhos de filas BullMQ-Pro apoiadas por Redis.

Mapa do aplicativo

Aplicativo	Caminho	Estrutura	Finalidade
Painel	`apps/zappway/dashboard`	Próximo.js	IU principal do SaaS
Blogue	`apps/zappway/blog`	Próximo.js	Blog de marketing
Documentos	`apps/zappway/docs`	Baseado em MDX	Documentação do produto
Página inicial	`apps/zappway/lp`	Próximo.js	Página inicial
Serviços aos Trabalhadores	`apps/workers-services`	Próximo.js	Trabalhadores em segundo plano + Ponte WA
ZappFlux	`apps/zappflux`	Próximo.js	Produto secundário (BD compartilhado)

Mapa do pacote

Pacote	Caminho	Finalidade
`@zappway/prisma`	`packages/zappway/prisma`	Esquema Prisma, cliente, exportações de navegador
`@zappway/lib`	`packages/zappway/lib`	Lógica de negócios principal (cerca de 160 arquivos)
`@zappway/integrations`	`packages/zappway/integrations`	Adaptadores de 13 canais
`@zappway/ui`	`packages/zappway/ui`	Componentes React compartilhados

2. Camada de banco de dados

Fonte: packages/zappway/prisma/schema.prisma (1548 linhas) · 33 modelos · 23 enums PostgreSQL via Prisma com recursos de visualização fullTextSearch e fullTextIndex habilitados. O modelo Organization é o limite do locatário raiz – todas as outras entidades têm como escopo direto ou transitivo.

Inventário completo de modelos

#	Modelo	Chave do inquilino	Finalidade
1	`User`	—	Conta de usuário da plataforma
2	`Organization`	`id` (raiz)	Contêiner inquilino
3	`Membership`	`organizationId`	Relacionamento usuário-organização (RBAC)
4	`ApiKey`	`organizationId`	Acesso programático
5	`Usage`	`organizationId`	Acompanhamento de uso de faturamento
6	`Agent`	`organizationId`	Definição de funcionário de IA
7	`Datastore`	`organizationId`	Contêiner da base de conhecimento
8	`AppDatasource`	`organizationId`	Fonte de dados individual
9	`Conversation`	`organizationId`	Sessão de bate-papo
10	`Message`	via conversa	Mensagem individual
11	`Tool`	via Agente	Definição de ferramenta de agente
12	`Form`	via Agente	Forma dinâmica
13	`FormSubmission`	via Formulário	Resposta do formulário
14	`Contact`	`organizationId`	Contato CRM
15	`Subscription`	`organizationId`	Plano de cobrança
16	`Product`	—	Produto listrado
17	`Price`	—	Preço da faixa
18	`Account`	`userId`	Link do provedor OAuth
19	`Session`	`organizationId`	Sessão de autenticação
20	`VerificationToken`	—	Verificação de e-mail
21	`ServiceProvider`	`organizationId`	Credenciais de integração
22	`ActionApproval`	via conversa	Solicitação de aprovação de ferramenta
23	`Attachment`	por mensagem	Anexo de mensagem
24	`ExternalIntegration`	via Agente	Webhook/configuração externa
25	`LLMTaskOutput`	`organizationId`	Resultado da tarefa assíncrona LLM
26	`MailInbox`	`organizationId`	Configuração da caixa de entrada de e-mail
27	`ConversationCrmTag`	`organizationId`	Marcação de CRM
28	`Lead`	`organizationId`	Captura de leads
29	`XPBNPEval`	—	Avaliação de teste A/B
30	`AgentsOnDatastores`	—	M:N junção entre agente e armazenamento de dados
31	`Coupon`	—	Cupom de cobrança
32	`UserApiKey`	`userId`	Chave de API em nível de usuário
33	`CrmLog`	`organizationId`	Registro de atividades de CRM

Enums-chave

Enum	Valores de amostra
`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`	Mais de 50 valores de enum de modelo - consulte Seção 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. Arquitetura de filas e trabalhadores

Fonte: packages/zappway/lib/types/index.ts, apps/workers-services/workers/ Três filas BullMQ-Pro dedicadas separam as preocupações. A fila load-datasource é a fila ativa principal; os outros dois estão parcialmente implementados.

Configuração do Worker — Carregador de fonte de dados

Configuração	Valor	Substituição de ambiente
Nome da fila	`load-datasource`	—
Simultaneidade	3	`DS_WORKER_CONCURRENCY`
Duração do bloqueio	8 minutos	`DS_BULL_LOCK_DURATION_MS`
Intervalo paralisado	anos 90	`DS_BULL_STALLED_INTERVAL_MS`
Contagem máxima paralisada	2	`DS_BULL_MAX_STALLED_COUNT`
Bloqueio de desduplicação TTL	10 minutos	`DS_JOB_LOCK_TTL_MS`
Remover ao concluir	Últimos 1000	—
Remover em caso de falha	Últimos 5.000	—

Mecanismo de desduplicação: Redis SET NX com chave ld:lock:{datasourceId} impede que a mesma fonte de dados seja executada em paralelo. Desligamento Gracioso: Lida com SIGTERM e SIGINT – fecha o trabalhador e sai do Redis de forma limpa.

Inventário de Trabalhadores

Trabalhador	Fila	Estado
`datasource-loader.ts`	`load-datasource`	✅ Ativo
`check-and-sync-cron.ts`	baseado em cron	✅ Ativo
`generate-rag.ts`	`generate-rag-document`	✅ Ativo
`index-media-memory.ts`	`index-media-memory`	✅ Ativo
`check-stalled.ts`	interno	✅ Ativo
`trial-expiry-check.ts`	baseado em cron	✅ Ativo
`usage-reconciler.ts`	baseado em cron	✅ Ativo
`scheduler.ts`	orquestrador	✅ Ativo

4. Mecanismo de ingestão e carregadores

Fonte: packages/zappway/lib/datastores/datasources/, packages/zappway/lib/loaders/ Todos os carregadores estendem DatasourceLoaderBase. O ponto de entrada taskLoadDatasource() seleciona o carregador correto em tempo de execução com base em DatasourceType. A saída é uma matriz AppDocument[] normalizada alimentada no mecanismo de chunking e depois no Qdrant.

Mapeamento do carregador

Tipo de fonte de dados	Carregador	Fonte
`web_page`	`WebPageLoader`	Busca de URL
`web_site`	`WebSiteLoader`	Mapa do site / rastreamento
`file`	`FileLoader`	Carregamento S3
`text`	`TextLoader`	Entrada de texto bruto
`qa`	`QALoader`	Pares de perguntas e respostas
`youtube_video`	`YouTubeLoader`	API do YouTube
`youtube_bulk`	`YouTubeLoader`	Multi-vídeo
`google_drive_file`	`GoogleDriveLoader`	API do Drive
`google_drive_folder`	`GoogleDriveLoader`	API do Drive
`notion`	`NotionLoader`	API de noção
`notion_page`	`NotionLoader`	API de noção
`api`	`APILoader`	Ponto de extremidade HTTP

Carregador de site – Detalhe do pipeline

Fonte: packages/zappway/lib/loaders/web-site.ts (515 linhas) O WebSiteLoader é o carregador mais complexo. Seu pipeline é executado em 6 estágios: (1) Discovery — analisa XML do mapa do site ou rastreia via findDomainPages(); (2) Normalização — desduplicação de URL, remoção de parâmetros UTM, nome de host em minúsculas; (3) Filtragem de lista negra — aplica a configuração black_listed_urls; (4) Investigação HTTP — HEAD → GET com reparo de caminho semver em 404s; (5) Gerenciamento infantil — atualiza web_page fontes de dados infantis, exclui órfãos; (6) Enfileiramento — emite trabalhos filhos com pontuações de prioridade (home = 5, mapa do site = 8, outros = 10). A simultaneidade é limitada a 6 por meio de mapWithConcurrency. Limite do plano aplicado via accountConfig[plan].limits.maxWebsiteURL (padrão: 25).

5. Camada de banco de dados vetorial - Qdrant

Fonte: packages/zappway/lib/datastores/qdrant.ts (731 linhas) Cada Datastore é mapeado para exatamente uma coleção Qdrant chamada zw_{datastoreId}, fornecendo isolamento vetorial estrito por locatário. QdrantManager inclui uma rotina de migração automática que detecta incompatibilidades de dimensões ou métricas de distância e recria a coleção de forma transparente, permitindo atualizações de modelos de incorporação sem tempo de inatividade.

Configuração da coleção

Parâmetro	Valor
Tamanho do vetor	3072
Métrica de distância	Cosseno
Nome da coleção	`zw_{datastoreId}`
HNSW `m`	16
HNSW `ef_construct`	100
Quantização	Escalar Int8 — percentil 99
Carga útil no disco	`true`
Consistência de gravação	`majority`

Esquema de carga útil (por ponto)

Campo	Tipo	Finalidade
`datastore_id`	corda	Armazenamento de dados com escopo de locatário
`datasource_id`	corda	Documento fonte
`datasource_hash`	corda	Hash de conteúdo para desduplicação
`chunk_hash`	corda	Hash de pedaço individual
`chunk_offset`	inteiro	Posição no documento
`text`	corda	Conteúdo do texto original
`tags`	string[]	Tags definidas pelo usuário
`custom_id`	corda	Referência externa
`page_number`	inteiro	Número da página do PDF
`total_pages`	inteiro	Total de páginas PDF

6. Incorporação de pipeline

Fonte: packages/zappway/lib/datastores/gemini-embeddings.ts, packages/zappway/lib/multimodal-memory/ Todos os embeddings usam Gemini Embedding 2 Preview, produzindo vetores de 3.072 dimensões que correspondem ao VECTOR_SIZE do Qdrant. O pipeline usa valores taskType assimétricos por site de chamada — RETRIEVAL_DOCUMENT durante a ingestão e RETRIEVAL_QUERY no momento da pesquisa — o que é crítico para a qualidade da recuperação com o modelo de incorporação assimétrica do Gemini.

Configuração

Parâmetro	Valor
Modelo	`gemini-embedding-2-preview`
Dimensões de saída	3072
Tamanho do lote	100 (limite de API por `batchEmbedContents`)
Autenticação	`x-goog-api-key` — ambiente `GOOGLE_AI_API_KEY`

Suporte multimodal

embedMultimodal() aceita GeminiPart[][] onde cada parte pode ser { text } ou { inlineData: { mimeType, data } } (imagens codificadas em base64, quadros de vídeo, áudio, páginas PDF). Isso incorpora conteúdo não textual no mesmo espaço de 3.072 dimensões que o texto, permitindo uma verdadeira pesquisa semântica multimodal. O módulo multimodal-memory/ fornece indexação dedicada (indexer.ts — 24,5 KB), chunkers específicos de mídia (media-chunkers.ts), gerenciamento de coleção, pesquisa e acionadores de fila assíncrona.

7. RAG e pipeline de recuperação

Fonte: packages/zappway/lib/chat-v4/rag.ts (493 linhas) ZappWay implementa Multi-Shot Adaptive RAG com até 6 tentativas de recuperação progressiva em 3 níveis de qualidade. Cada tentativa relaxa os limites de similaridade para maximizar a recuperação, enquanto evaluateRagQuality() permite a saída antecipada quando os resultados são fortes o suficiente. Um disjuntor evita falhas em cascata e ragMemo (cache na memória) desduplica tentativas idênticas em uma sessão.

Limites adaptativos

Tentativa	Etiqueta	Modo Profundo	Normais	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`	0h30	0,25	100

Modo profundo é acionado por shouldFavorDeepRag(query) e aplica limites iniciais mais altos. minUcount é 1 para consultas de armazenamento de dados único e 2 para consultas de vários armazenamentos de dados. Os tempos limite variam de 8s (Nível 1) a 12s (Nível 3), limitados pelo orçamento restante do chat. Se remainingMs() < 120s, o máximo de tentativas é reduzido para 4.

8. Mecanismo de bate-papo e conversação

Fonte: packages/zappway/lib/chat-v4/chat.ts (1147 linhas), packages/zappway/lib/agent/tools/ A função de bate-papo orquestra a montagem do prompt do sistema, o truncamento do histórico de mensagens, o RAG multi-shot, a construção de ferramentas de tempo de execução, a execução do LLM com streaming e a cadeia de fallback do modelo completo – tudo dentro de um orçamento de tempo compartilhado aplicado em cada ponto de verificação.

Tipos de eventos SSE

Evento	Finalidade
`answer`	Delta de texto transmitido
`tool_call`	Notificação de invocação de ferramenta
`endpoint_response`	Dados de resposta da ferramenta HTTP
`step`	Indicador de etapas de processamento
`metadata`	Uso do modelo, fontes, janela de contexto
`error`	Notificação de erro
`done`	Sinal de conclusão de fluxo

Ferramentas de tempo de execução

Arquivo de ferramenta	Tipo de ferramenta	Finalidade
`datastore.ts`	`datastore`	RAG dinâmico dentro do loop de ferramentas
`form.ts`	`form`	Apresentar e coletar formulários dinâmicos
`http.ts`	`http`	Chame APIs externas
`request-human.ts`	`request_human`	Transferência para agente humano
`lead-capture.ts`	`lead_capture`	Capturar informações do visitante
`payment.ts`	`payment`	Initiate payment flow
`mark-as-resolved.ts`	`mark_as_resolved`	Fechar ticket de suporte
`ui.ts`	Renderização da interface do usuário	Componentes de UI personalizados

9. Isolamento e autenticação multilocatário

Fontes: packages/zappway/lib/auth/authConfig.ts, authAdapter.ts e authProviders.ts Auth.js Core processa diretamente as requisições HTTP do servidor com um adaptador Prisma personalizado; next-auth/react permanece restrito ao cliente. Quatro métodos de login são suportados. No primeiro login, a plataforma provisiona automaticamente toda a pilha de locatários de forma atômica.

Isolamento de locatário por camada

Camada	Mecanismo
Banco de dados	`organizationId` em cada modelo de locatário
API	O middleware de sessão injeta `organization` da sessão
Banco de dados vetorial	Uma coleção Qdrant por armazenamento de dados (`zw_{datastoreId}`)
Armazenamento de arquivos	Prefixo S3 `organizations/{orgId}/`
Filas	`organizationId` transportado em cada carga útil do trabalho

Modelo RBAC

Função	Escopo	Acesso
`SUPERADMIN`	Globais	Sistema completo
`CUSTOMER`	Globais	Usuário padrão
`OWNER`	Organização	Gerenciamento completo da organização
`ADMIN`	Organização	Gerenciar agentes e armazenamentos de dados
`USER`	Organização	Somente leitura

Configuração da Sessão

Configuração	Produção	Desenvolvimento
Estratégia	`database`	`database`
Nome do cookie	`__Secure-authjs.session-token`	`authjs.session-token`
Domínio de Cookies	`.{rootDomain}`	`undefined`
Seguro	`true`	`false`

Suporte local: 37 localidades, incluindo RTL (árabe, hebraico, persa, urdu). Ordem de resolução: caminho do URL → cookie NEXT_LOCALE → cookie i18next → cabeçalho Accept-Language → padrão en.

10. Sincronizar orquestrador

Fonte: apps/workers-services/workers/check-and-sync-cron.ts Um trabalhador orientado por cron verifica todas as fontes de dados com status = synched, filtra por lastSyncAt + syncInterval e distribui trabalhos load-datasource individuais. Um trabalhador check-stalled lida com a recuperação de fontes de dados presas no status running além de um limite configurável.

11. Integrações e canais externos

Fonte: packages/zappway/integrations/ — adaptadores de 13 canais Todos os canais normalizam as mensagens de entrada para o mesmo modelo interno Conversation + Message e roteiam através do mecanismo unificado chat-v4.

Capacidades do canal

Canal	Direção	Transmissão	Suporte de formulário
`dashboard`	Bidirecional	ESS	Sim
`website`	Bidirecional	ESS	Sim
`whatsapp`	Bidirecional	Não (webhook)	Limitado
`telegram`	Bidirecional	Não (webhook)	Limitado
`slack`	Bidirecional	Não (webhook)	Não
`crisp`	Bidirecional	Não (webhook)	Não
`mail`	Assíncrono	Não	Não
`api`	Solicitação/Resposta	Opcional	Não
`zapier`	Webhook	Não	Não
`form`	Envio de formulário	Não	Sim
`zendesk`	Bidirecional	Não (webhook)	Não
`messenger`	Bidirecional	Não (webhook)	Não
`instagram`	Bidirecional	Não (webhook)	Não

Autenticação do Provedor de Serviços

Tipo	Mecanismo de autenticação
`website`	Chave API
`whatsapp`	Token da API da nuvem
`telegram`	Token de bot
`slack`	OAuth
`crisp`	Chave API + ID do site
`zendesk`	Token de API
`messenger` / `instagram`	Token de acesso à página
`notion`	Token de integração
`google_drive`	Token de atualização OAuth
`zapier`	URL do webhook

12. Armazenamento de arquivos e pipeline de mídia

Fonte: packages/zappway/lib/aws.ts Suporta armazenamento compatível com S3 (AWS S3, Cloudflare R2, MinIO) via AWS SDK v3. Os arquivos são carregados por meio de URLs pré-assinados, armazenados em organizations/{orgId}/ e extraídos por FileLoader para extração e ingestão.

Variáveis de ambiente S3

Variável	Finalidade
`APP_AWS_REGION`	Região AWS
`APP_AWS_ACCESS_KEY`	ID da chave de acesso
`APP_AWS_SECRET_KEY`	Chave de acesso secreta
`APP_AWS_S3_ENDPOINT`	Endpoint personalizado (R2/MinIO)
`APP_AWS_S3_FORCE_PATH_STYLE`	Estilo de caminho para R2/MinIO
`APP_AWS_S3_BUCKET`	Balde de destino

13. Orquestração LLM e roteador modelo

Fonte: packages/zappway/lib/config.ts (943 linhas), packages/zappway/lib/chat-model/model.ts (745 linhas) 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.

Inventário de Modelos

🧠 OpenAI — Direto

Modelo	Máximo de tokens	Custo
GPT-4o/GPT-4o Mini	128K	15/4
GPT-5/Mini/Nano	400 mil	15/5/4
Bate-papo GPT-5.1 / 5.1	400 mil	15/12
GPT-5.2 / 5.2 Bate-papo / 5.2 Bate-papo mais recente	400 mil	20/15/15
Bate-papo GPT-5.3 mais recente / Codex 5.3	400K/128K	15
GPT-5.4 / 5.4 Mini / 5.4 Nano	400 mil	15/6/5

🟡 Google — Direto via API Gemini

Modelo	Máximo de tokens	Custo
Gêmeos Flash 2.0 / 2.5	1 milhão	5/10
Gêmeos Pro 2.5	1 milhão	12
Gêmeos 3 Pro/3 Flash	1 milhão	15/10
Imagem Pro de Gêmeos 3	64K	15
Gêmeos 3.1 Flash Lite / Imagem Flash / Pro	1M/64K/1M	5/8/15

🔶 Antrópico — via OpenRouter

Modelo	Máximo de tokens	Custo
Claude 3.5 Haiku / 3.5 Soneto	200 mil	12/15
Soneto de Cláudio 4	200 mil	15
Claude 4.5 Haiku / 4.5 Soneto	200 mil	12/15
Claude Opus 4.5 / Opus 4.6 / Soneto 4.6	200 mil	20/20/15

Outros provedores — via OpenRouter

Modelo	Provedor	Custo
DeepSeekV3.2/R1	DeepSeek	5/8
Llama-4 Maverick / Escoteiro	Meta	10/5
Mistral Grande 2512 / 8x22B / 8x7B / Pequeno Criativo	Mistral	5/5/2/2
Sonar Pro	Perplexidade	15
Grok 4 / 4.1 Rápido	xAI	15/5
Nova Premier / Nova 2 Lite	Amazônia	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 nível gratuito: gpt_4o_mini, gpt_5_mini, gpt_5_nano, gpt_5_4_mini, gpt_5_4_nano, gemini_flash_2_0

Importante: Os modelos da família GPT-5 não suportam ajuste manual de temperatura — eles usam reconhecimento automático de temperatura.

14. Observabilidade e monitoramento

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

Componente	Tecnologia	Estado
Registrador principal	Pino	✅ Ativo
Impressão bonita	pino-bonito	✅ Ativo
Nuvem Axioma	@axiomhq/pino	❌ Comentado
Registrador de bate-papo	Criança Pino `logChat`	✅ Ativo
Rastreamento de erros	Sentinela (cliente + servidor + borda)	✅ Ativo

Os trabalhadores publicam uma carga útil WorkerHealth no Redis (health:worker:{name}, TTL de 30s) a cada 10s. Campos: status, startedAt, lastActivityAt, jobsProcessed, jobsFailed, queueLength, system.memoryMB, system.uptimeMs. Exposto via /api/workers/health. Os trabalhadores também transmitem logs em tempo real para o canal Redis Pub/Sub logs:datasource para monitoramento do painel ao vivo.

15. Lacunas e recomendações

Lacunas identificadas

#	Área	Lacuna	Gravidade
1	Observabilidade	Integração do Axiom comentada – sem registro em nuvem na produção	🟡 Médio
2	Limitação de taxa	Nenhuma limitação de taxa visível nos endpoints da API de chat	🔴 Alto
3	Fila DLQ	Nenhuma fila de mensagens mortas para trabalhos com falha permanente	🟡 Médio
4	Incorporando substituto	Provedor de incorporação único (Gemini) — sem alternativa se a API estiver inoperante	🟡 Médio
5	Backup de banco de dados vetorial	Nenhuma estratégia documentada de backup/instantâneo do Qdrant	🟡 Médio
6	Cobertura de teste	Nenhum arquivo de teste encontrado nos diretórios verificados	🔴 Alto

Recomendações

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.

Pontos fortes da arquitetura

Força	Detalhe
RAG multidisparo	Recuperação adaptativa de 6 tentativas com avaliação de qualidade e disjuntor
Migração automática	Coleção Qdrant recriada de forma transparente na incorporação da mudança de modelo
Desligamento Gracioso	Todos os trabalhadores manuseiam `SIGTERM` / `SIGINT` de forma limpa
Bloqueios de desduplicação	Redis `SET NX` impede o processamento paralelo da mesma fonte de dados
Gestão Orçamentária	Orçamento de tempo aplicado em cada ponto de verificação no pipeline de chat
Mais de 50 modelos	Interface unificada OpenAI-SDK em 12 provedores
Verdadeiro Multimodal	Incorporação, fragmentação e pesquisa multimodal ponta a ponta de imagens, áudio e vídeo
Isolamento total do inquilino	Coleções Qdrant separadas e prefixos S3 por organização

Vocabulário

Prazo	Descrição
Armazenamento de dados	Contêiner de fontes de dados — mapeia para uma coleção Qdrant (`zw_{datastoreId}`)
Fonte de dados	Fonte de dados individual — `web_page`, `file`, `youtube_video`, etc.
AppDocumento	Saída de formato de documento normalizado por todos os carregadores
RAG Multi-Shot	Recuperação adaptativa com até 6 tentativas progressivas em 3 níveis de qualidade
Disjuntor	Interrompe o RAG após 3 falhas consecutivas por 60s para evitar erros em cascata
Modo profundo	Modo RAG de alto limite acionado por `shouldFavorDeepRag(query)`
BullMQ-Pro	Fila de trabalhos apoiada por Redis com agendamento avançado e recursos de fluxo
Qdrant	Banco de dados vetorial usado para pesquisa semântica multimodal
Incorporação Gêmeos 2	Modelo de incorporação multimodal produzindo vetores de 3.072 dimensões
TaskType	Modo de incorporação assimétrica: `RETRIEVAL_DOCUMENT` para ingestão, `RETRIEVAL_QUERY` para pesquisa
AgentsOnDatastores	Tabela de junção M:N ligando Agentes a Datastores
HNSW	Mundo Pequeno Navegável Hierárquico — índice aproximado do vizinho mais próximo em Qdrant

· Última atualização: março de 2026

​🔢 Índice

​1. Arquitetura geral do sistema

​Mapa do aplicativo

​Mapa do pacote

​2. Camada de banco de dados

​Inventário completo de modelos

​Enums-chave

​3. Arquitetura de filas e trabalhadores

​Configuração do Worker — Carregador de fonte de dados

​Inventário de Trabalhadores

​4. Mecanismo de ingestão e carregadores

​Mapeamento do carregador

​Carregador de site – Detalhe do pipeline

​5. Camada de banco de dados vetorial - Qdrant

​Configuração da coleção

​Esquema de carga útil (por ponto)

​6. Incorporação de pipeline

​Configuração

​Suporte multimodal

​7. RAG e pipeline de recuperação

​Limites adaptativos

​8. Mecanismo de bate-papo e conversação

​Tipos de eventos SSE

​Ferramentas de tempo de execução

​9. Isolamento e autenticação multilocatário

​Isolamento de locatário por camada

​Modelo RBAC

​Configuração da Sessão

​10. Sincronizar orquestrador

​11. Integrações e canais externos

​Capacidades do canal

​Autenticação do Provedor de Serviços

​12. Armazenamento de arquivos e pipeline de mídia

​Variáveis ​​de ambiente S3

​13. Orquestração LLM e roteador modelo

​Inventário de Modelos

​🧠 OpenAI — Direto

​🟡 Google — Direto via API Gemini

​🔶 Antrópico — via OpenRouter

​Outros provedores — via OpenRouter

​14. Observabilidade e monitoramento

​15. Lacunas e recomendações

​Lacunas identificadas

​Recomendações

​Pontos fortes da arquitetura

​Vocabulário