Documentação Técnica
Referência de arquitetura, dados, pipeline, deploy e escala da plataforma. Público: engenharia, infra e operação. Use o índice "Nesta página" (à direita) para navegar.
1. Visão geral
O AURA é uma plataforma multi-tenant de mensageria conversacional (inbound): recebe mensagens de ~16 canais (WhatsApp/Meta, Instagram, Messenger, Telegram, Teams, Slack, Google Chat, Zoom, Twilio, Gupshup, Positus, SERPRO, Botmaker, widget de site…), processa cada conversa por uma máquina de estados (fluxo) versionada com NLU (detecção de intenção) e IA generativa (RAG), e responde via bot ou atendimento humano (filas, transbordo, supervisão, copiloto). Inclui voz/vídeo (LiveKit + chamada nativa WhatsApp), autenticação do cliente final (gov.br/Google/OIDC), base de conhecimento, painéis (dashboards no-code) e billing por plano.
Stack
Camada | Tecnologia |
|---|---|
API / Workers | Python + FastAPI + SQLAlchemy 2.0 async (asyncpg) |
Banco | PostgreSQL 16 + pgvector — schema-por-tenant |
Filas | Redis + BullMQ (lib Python) com outbox transacional |
NLU | Microserviço próprio (fastembed/ONNX, MiniLM multilíngue 384-d, CPU, sem GPU) |
Storage | MinIO (S3), anexos e gravações |
Auth | Keycloak 26 (console) + OIDC do cliente final (gov.br/Google) |
Voz/Vídeo | LiveKit (SFU) + callbridge (WebRTC/aiortc p/ chamada nativa WhatsApp) |
Frontend | React 18 + Vite + TS (console) · widget JS embarcável |
Deploy | docker-compose (dev) · k8s + ArgoCD (HML/PROD CentralIT) |
2. Arquitetura
Cliente final Console (atendente/admin)
WhatsApp/Telegram/Widget/... React (polling 4s)
│ webhook / WS
▼
┌────────────────────────────── API FastAPI ───────…
│ /webhook/{tenant}/{broker} → grava mensagem + out…
│ /ws (widget) · /api/* (console) · /metrics · …
└────────────────────────────────────┬───────────────…
│ control.outbox
┌──────▼──────┐ relay …
│ WORKER │──► fila …
│ (4 filas + │ me… kb_indexar
│ 4 sweepers)│──► máqu…
└──────┬──────┘──► entr… conversa)
NLU :8001 ◄─────────┤
(classify/embed) │
LLM (RAG) ◄─────────┘Os 4 subprocessos do pipeline: Receber (webhook, barato) → Baixar anexo (worker→MinIO, anti-SSRF) → Processar (worker, máquina de estados, lock por conversa) → Entregar (HTTP do broker ou WebSocket via Redis pub/sub).
Decisões estruturais:
- Outbox transacional (sem dual-write): todo job nasce como linha em control.outbox na mesma transação da escrita operacional; o relay do worker drena com FOR UPDATE SKIP LOCKED (batch 200, tick 0,5 s) e despacha ao BullMQ com jobId = outbox.id (redespacho idempotente). Entrega at-least-once.
- Ordem por conversa na entrega: entrega.py re-agenda (200 ms) se houver saída anterior pendente da mesma conversa — FIFO por chave, com idempotência do último salto (não reenvia o já entregue).
- WebSocket escalável: o WS do widget faz fan-out via Redis pub/sub (WS_CHANNEL) — cada réplica da API mantém as próprias conexões e recebe broadcast. (A restrição single-replica é só do callbridge.)
3. Multi-tenancy
- Schema-por-tenant: public (tenant, plano, cliente, fornecedor, catálogo, auditoria) · control (outbox, job_log) · tenant_<hex> (tabelas operacionais).
- Isolamento por SET LOCAL search_path por transação; statement_cache_size=0 no asyncpg. Tabelas operacionais não têm tenant_id.
- Tenant sempre explícito na borda: rota /webhook/{tenant_id}/{broker_type}, em todo job de fila e nos callbacks Platform. Não há índice global "channel→tenant".
- TENANT_ISOLATION_ENFORCE (produção): com Bearer não-admin, o claim tenant_id do JWT precisa bater com o tenant da requisição (403 TenantScopeError). Exige mapper tenant_id no realm + backfill (python -m app.manage backfill-tenant).
- Migrações por tenant com advisory lock por schema — paralelas e isoladas (falha de um tenant não contamina os demais).
4. Modelo de dados
ORM em backend/app/core/orm.py (SQLAlchemy 2.0, Mapped/mapped_column); DDL idempotente por versão em core/sql.py. PostgreSQL 16 + pgvector. UUIDs como PK (gen_random_uuid()), timestamps timezone=True.
Três schemas
public ── globais (control-plane): tenants, cliente…
control ── pipeline: outbox (fila transacional) + jo…
tenant_<hex> ── operacionais, UM por tenant (isolamen…Schema control
Tabela | Colunas-chave | Papel |
|---|---|---|
outbox | id, tenant_id, queue, name, payload(JSONB), created_at, dispatched_at | Fila transacional: o job nasce aqui na mesma transação da escrita; o relay drena (dispatched_at IS NULL) |
job_log | id, job_id, queue, name, tenant_id, correlation_id, conversation_id, status, attempt, resultado, erro, iniciado_em, finalizado_em, duracao_ms | Trilha de cada job. status ∈ running | ok | failed | rejeitado. Índices: (tenant_id, iniciado_em), (status, iniciado_em), (correlation_id). |
Schema public (globais)
Tabela | Colunas-chave | Papel |
|---|---|---|
tenant | id, nome, schema(UNIQUE), cliente_id, criado_em | Registro do tenant → aponta para o schema operacional. |
tenant_schema_migrations | schema, version (PK composta), applied_at | Controle de migração por schema. |
cliente | id, nome, documento, email, plano_id(FK plano), razao_social, telefone, contrato_status, contrato_inicio/fim, parametros(JSONB), ativo | Contrato. contrato_status ∈ trial | ativo | suspenso | cancelado. |
plano / plano_catalogo | plano: limite_mensagens_mes, preco_centavos, ativo; catálogo: features/extras/precos(JSONB) | Plano do tenant + catálogo comercial global (editável pelo admin). |
catalog_vendors | slug, name, auth_schema(JSONB), docs_url… | Vendors de integração (CITSmart, Agility, GLPI…). |
catalog_blocks | vendor_id(FK CASCADE), slug, kind, input_schema(JSONB); UNIQUE(vendor_id, slug) | Ações do vendor. kind ∈ http | mcp_tool. |
fornecedor · provisioning_config · agent_status (presença do atendente) · agente_tenant (vínculo agente → workspace, por fila e por cadastro) · admin_audit_log | — | Apoio + auditoria administrativa. |
Schema tenant_ (operacionais)
Hierarquia: CHATBOT → (CHANNEL · FLOW) → CONVERSATION → MESSAGE → ATTACHMENT, com CONTATO cruzando os canais.
Tabela | Colunas-chave / constraints | Papel |
|---|---|---|
chatbot | id, nome, ativo, config(JSONB) | Assistente. |
channel | broker_type, channel_id (UNIQUE), credenciais(JSONB cifrado), config(JSONB), chat_id | Conexão de canal. |
flow | chat_id, versao; UNIQUE(chat_id, versao) | Fluxo versionado por chat (publicar arquiva a anterior). |
node | flow_id(FK CASCADE), node_key, cfg(JSONB); UNIQUE(flow_id, node_key) | Nó normalizado (populado ao publicar). |
edge | flow_id(FK CASCADE), source, target, … | Aresta do fluxo. |
conversation | canal_id(FK channel), user_id; UNIQUE(canal_id, user_id); contexto(JSONB), controle, contato_id(FK contato), fluxo_versao | controle ∈ bot | humano. contexto guarda variáveis, _handoff, _csat, _ia_hist. Fixa a versão do fluxo no recebimento. |
message | conversa_id(FK), direcao, id_externo; UNIQUE(direcao, id_externo); entrega_status/erro, processada, importante | Idempotência por (direcao, id_externo). importante = estrela do atendente. |
attachment | mensagem_id(FK), status | status: pendente → baixado | erro (MinIO). |
contato | id, nome, atributos(JSONB) | Perfil único do cliente (user_info dinâmico). |
contato_identidade | contato_id(FK), canal, id_externo; UNIQUE(canal, id_externo) | Costura cross-canal. canal = broker_type ou chave (cpf/telefone/email); id_externo = user_id ou o valor da chave. |
intent / entity / nlu_log / entity_uso_log | exemplos por intenção; log com score/margem/motivo | NLU. motivo ∈ ok | baixa_confianca | ambiguo. |
knowledge_base / document / chunk | kb: status, chat_id(FK SET NULL); doc: status, meta(JSONB); chunk.embedding Vector(384) | RAG. Documento: pendente → processando → indexado | erro. |
ia_usage_log | tokens, custo_usd, latencia, status | Uso de LLM. status ∈ ok | fallback | erro | teto_mensal. |
service_queue | nome, ativa, config(JSONB) | Fila de atendimento humano (toda a regra na config). |
bloco_custom (v88) | nome, slug (UNIQUE), codigo, entradas(JSONB), saidas(JSONB), timeout_seg, http, dominios | Catálogo de blocos do workspace publicados a partir do bloco Código. O nó guarda só {bloco_id, params} — corrigir o bloco conserta todos os fluxos que o usam. |
email_caixa (v79) | endereco (UNIQUE), auth_tipo (senha | oauth2_google | oauth2_m365), fila_id(FK SET NULL), imap_*/smtp_*; senhas e secrets cifrados | N caixas de recebimento por tenant, cada uma vinculada a uma fila de e-mail (fila_id nulo = primeira fila de e-mail ativa). Google usa a conta de serviço do tenant em smtp_config. |
atendimento_log · chamada_log (voz: duracao_seg, egress/status/url) · notificacao (sininho: tipo, tom) · smtp_config (linha única, senha cifrada, notificacoes JSONB) · smtp_log (status ok|erro) · provider_event · webhook_log · log · tenant_integration (vendor_slug, credentials JSONB cifrado) | — | Apoio, auditoria e integrações. |
5. Autenticação e RBAC
- Console: Keycloak — OIDC Authorization Code + PKCE (implementação própria em frontend/src/lib/auth.ts, sem lib) e login por senha (ROPC) na tela própria; refresh silencioso. Papéis realm: aura_agente < aura_supervisor < aura_admin (+ aura_super_admin); os nomes sem prefixo seguem aceitos por retrocompatibilidade, e dentro da aplicação o nome é sempre o canônico (agente, supervisor…).
- Backend: valida JWT RS256 via JWKS, issuer ∈ KEYCLOAK_ISSUERS, azp == KEYCLOAK_CLIENT_ID; extrai {email, sub, roles, tenant_id}.
- X-Platform-Token (PLATFORM_TOKEN): credencial de plataforma para integrações e para o console (enviada sempre pelo front) — aceita como alternativa ao Bearer nos guards.
- Guards (deps.py): _auth (plataforma ou supervisor/admin) · _auth_plataforma (control-plane) · _agente (agente/supervisor/admin) · _exige_supervisor/_exige_admin · _exige_rbac(tenant, resource, action) — matriz RBAC por tenant (rbac_policy), aplicada no servidor.
- Cliente final: OIDC gov.br/Google/Keycloak via link de uso único no chat (HS256, exp 15 min, jti single-use no Redis, PKCE) — bloco auth do fluxo. Presets em OIDC_PROVIDERS.
- Rate limiting: não há no backend (se necessário, aplicar no ingress/nginx).
6. API REST
ROOT_PATH = /api/v1/omnichannel-platform (HML/PROD; vazio em dev). Swagger custom em /docs. 22 routers (backend/app/routers/):
Router | Recursos |
|---|---|
plataforma | control-plane: tenants, clientes, planos |
planos | plano do tenant, catálogo, faturas |
usuarios | usuários Keycloak, 1º acesso, reset, auditoria |
rbac | política RBAC por tenant (/api/rbac/policy, /my) |
chats / fluxos / intents / entities | assistentes; fluxos (+simular/testar-http, BPMN bpmn/exportar|importar, catálogo/validador flow/catalogo|validar, copiloto flow/copiloto[/disponivel] e flow/documentar, bloco Código flow/codigo/testar e CRUD /api/blocos); intenções NLU (+testar/importar/avaliar); entidades NER |
kb | base de conhecimento (texto/URL/upload, reindexar, buscar, testar) |
canais | canais/conexões, broker_types, widget config, upload/mídia |
filas | filas de atendimento + saúde de jobs/outbox + reprocessar DLQ |
atendimento | atendimento humano completo (status/ping/offline, distribuir, copiloto, platform send/sussurro/retomar/transferir/atribuir, export) |
chat | widget: histórico/reiniciar/read + WS /ws |
webhook | ingestão GET/POST /webhook/{tenant_id}/{broker_type} + log |
chamadas | voz: /api/call/token |
contatos / integracoes / analytics / auth_cliente | contatos; catálogo/integrações/SMTP/hyper; catálogo semântico + consulta dos painéis; OIDC cliente final |
monitor | dead-letter, NLU stats, uso de IA, métricas de negócio (§ observabilidade) |
sim | broker fake p/ testes (/_fake, /_sim) — só monta com SIM_ENABLED |
Integração com HyperAgent: nó "Agente IA" do fluxo cria issue via REST no HyperAgent (POST /api/companies/{id}/issues) e faz polling do comentário-resposta (vendor hyper_agents no catálogo). Unidirecional — só o AURA conhece o Hyper.
7. Pipeline de mensagens: outbox, filas e workers
Filas BullMQ (channels/queues.py)
- mensagens · anexos · broker_output · kb_indexar (+ dead_letter como DLQ nomeada, sem consumer — inspeção/replay).
- Job opts: attempts=5 (QUEUE_MAX_ATTEMPTS), backoff exponencial base 1 s, removeOnComplete=true, removeOnFail=1000.
- Worker opts: concurrency=5 (WORKER_CONCURRENCY), lockDuration=60 s, maxStalledCount=3, stalledInterval=15 s.
Processo worker (app/worker.py)
Um processo = 4 workers BullMQ + relay + 4 loops e um HTTP próprio na porta 9100 (/metrics, /health, /health/ready — readiness sonda DB+Redis a cada 10 s):
Loop | Cadência | Função |
|---|---|---|
run_relay | 0,5 s | outbox → BullMQ (batch 200, SKIP LOCKED, jobId idempotente) |
_sweep_inatividade | 20 s | encerra ociosos, expira presença (PRESENCA_TIMEOUT_SEG=180; saída avisada após PRESENCA_SAINDO_CARENCIA_SEG=45), devolve conversas de agentes "stale", distribui pendentes, anuncia posições, e-mails de SLA e resumo diário |
_sweep_rollup | 60 s | rollups que alimentam os painéis |
_sweep_humor | 30 s | classifica humor via LLM (planos com ia_base) |
Ciclo de vida do job (channels/lifecycle.py)
com_joblog(queue) envolve todo processor: valida tenant ativo (senão rejeitado, sem retry), grava control.job_log (running→ok/failed/dead_letter), copia para a DLQ ao esgotar attempts e emite métricas (jobs_total, job_duration_seconds).
DLQ e reprocesso
- Duplo registro: fila BullMQ dead_letter + control.job_log com status dead_letter.
- Inspeção: GET /api/admin/dead-letter. Reprocesso: POST /api/filas/reprocessar (refaz os getFailed() de mensagens/anexos/broker_output).
- Saúde: GET /api/filas (waiting/active/delayed/failed por fila + outbox_pendentes).
Debounce (channels/debounce.py)
Janela por canal (credenciais.debounce_ms) ou global (DEBOUNCE_MS, default 0): mensagens em rajada são coalescidas antes de processar (exceções: comandos /… e nós críticos como menu/form).
8. Motor de fluxo (máquina de estados)
Execução real em channels/processing/machine.py (flow.py de app/flows/ guarda o modelo puro/validação/simulador):
- processar_mensagem roda sob lock por conversa (exclusão mútua); trata jobs especiais: _aviso (nudge pré-timeout), _timeout (sem resposta → saída "tempo esgotado"), _auth_done (OIDC concluído), _debounce (coalesce), CSAT, assistente pausado, retomada cross-canal (CONTINUAR_CROSS_CANAL, janela 48 h).
- _avancar(...): encadeia nós automáticos até parar num nó de entrada ou terminal (guarda anti-loop: 50 iterações). Tipos de nó: choice, intent (NLU), ia (RAG), auth, handoff, assistente (entrega a outro chatbot: mesmo canal/histórico, fluxo e NLU do destino — human.entregar_a_assistente_tx), form, condition, action, webhook, integracao, email, entrada_api, codigo/bloco (Python em subprocesso — flows/sandbox*.py, codigo_node.py), agent (HyperAgent), delay, contato, split (A/B), gatilho, end.
- Contexto da conversa (conversation.contexto JSONB) é o backbone: variáveis capturadas, histórico de IA, snapshot de handoff (_handoff), CSAT.
- Nós caros são gated por plano (nlu, ia_base, integracoes).
- Timeouts de fluxo = jobs atrasados via outbox (_delay_ms).
Camadas em volta do editor (app/flows/)
Módulo | Papel |
|---|---|
catalogo.py | Fonte única dos tipos de bloco no backend (label, cfg aceito, transições, variáveis gravadas) — GET /api/flow/catalogo. É o contexto FIXO do copiloto: sem isto a IA inventa bloco. |
validador.py | validar(def) -> [Problema] (erro bloqueia, aviso alerta): tipo/cfg desconhecido, quando inválido, destino inexistente, órfão, beco sem saída, variável não gravada, handoff sem fila, ciclo sem espera. POST /api/flow/validar. |
mapa.py | Resumo determinístico da definicao (índice de blocos, transições, variáveis, integrações, caminhos, comentários, problemas). É o que entra no prompt — JSON cru de fluxo grande alucina. |
documentar.py / copiloto_fluxo.py / patch.py / ajuda.py | Documentação em markdown; turno de conversa devolvendo proposta + diff (nunca grava); operações de patch (add_no, alterar_no, remover_no, ligar…) preservando id/cfg/posição do que não foi tocado; FAQ de interface escrita à mão (caminho de tela é fato verificável — modelo pequeno erra o botão com confiança). |
bpmn.py (+ frontend/src/flow/bpmn.ts) | Serialização BPMN 2.0 com round-trip fiel (extensões aura:), gateway sintético para fan-out, raias derivadas do tipo. defusedxml no import (XXE/billion laughs, limites 4 MB / 20k elementos). A definicao não muda — camada de apresentação/serialização. |
sandbox.py / sandbox_runner.py / codigo_node.py | Bloco Código: Python do tenant em subprocesso com usuário próprio quando o ambiente permite (sandbox, não lê o ambiente do worker; sem o usuário na imagem ou sem CAP_SETUID/CAP_SETGID, roda como o processo pai e o log avisa), rlimits, timeout (teto 30 s) e env limpo; HTTP por RPC no processo pai (mantém o anti-SSRF) com allowlist de domínio. Escrever código = admin ou super_admin; no "Rodar agora" e em /api/flow/simular o admin precisa também de "assistentes" no tenant informado; usar = qualquer um. |
repo/blocos.py | CRUD do catálogo do workspace (bloco_custom, v88) — o nó guarda {bloco_id, params}. |
9. NLU e IA (RAG)
NLU (microserviço backend/nlu/, porta 8001, imagem própria)
- fastembed/ONNX, CPU-only; modelo paraphrase-multilingual-MiniLM-L12-v2 (384-d — casa com chunk.embedding). Reranker lazy BAAI/bge-reranker-base.
- Endpoints: GET /health · POST /classify (cosseno + 2 critérios: confiança ≥ limiar do nó e margem ≥ 0,06; motivos ok/baixa_confianca/ambiguo) · POST /embed · POST /rerank. Cache L1 memória + L2 Redis.
- Sem treino: o cliente dá frases de exemplo por intenção; "retreino" = editar exemplos. Benchmark: MiniLM 77–80% top-1 e 91–95% de rejeição de fora-de-escopo (calibração > acurácia bruta); 160 req/s por réplica; limiar default do nó = 0,6.
- Cliente resiliente (nlu_client.py): classify fail-open (indisponível → segue fluxo sem intenção), embed propaga erro (documento reprocessa).
IA generativa / RAG (channels/ia_base.py, kb.py)
- Ingestão: texto/URL (crawler BFS anti-SSRF)/upload (pdf/txt/md/csv) → chunking ~1000 chars (overlap 150) → embeddings via NLU (lotes 16, backoff, divisão sob OOM) → pgvector.
- Busca híbrida: densa (cosseno) + full-text PT fundidas por RRF (K=60) + rerank opcional (cross-encoder). Confiança: alta ≥ 0,62 · média ≥ 0,45.
- LLM com teto mensal de tokens por tenant (ia_usage_log com status teto_mensal), fallback e roteamento por sentimento; timeout 60 s (LLM_TIMEOUT, por chamada 1–120 s).
10. Atendimento humano
channels/human.py (+ human_config.py, copiloto.py):
- Entrada na fila (avaliar_entrada: ok/bloqueado/sem_agentes — horário/bloqueio por config), distribuição ao agente disponível menos carregado, anúncio de posição na fila, protocolo.
- Controle bot↔humano na conversa; interfaces Platform: platform_send (com anexos), sussurro (supervisor→agente), platform_retomar (volta ao bot), transferir, atribuir.
- Presença por WebSocket (/api/me/presenca) + aviso ao fechar a página (/api/me/saindo) + heartbeat HTTP de reserva (/api/me/ping): quem fecha a aba sai da distribuição na hora e, sem voltar em PRESENCA_SAINDO_CARENCIA_SEG=45, tem as conversas devolvidas à fila; sem WebSocket, timeout de 180 s, expiração por inatividade, encerramento por palavra-chave, CSAT pós-atendimento, e-mails operacionais (SLA estourado, conversa devolvida, canal em queda, resumo diário).
- Copiloto (copiloto.py): sugestões de resposta ao atendente + varredura de humor das conversas via LLM (sweep 30 s, planos ia_base).
11. Brokers (canais)
17 drivers auto-registrados (channels/brokers/, interface base.py: receive, verificar_assinatura, verify_get, send, send_template, iniciar_chamada, mark_as_read, testar_conexao, listar_modelos):
widget · fake (testes) · meta_whatsapp (o maior: HMAC, verify handshake, templates, calling) · meta_messenger · meta_instagram · telegram · twilio_whatsapp · twilio_sms · slack · teams (reply-addr por conversa) · googlechat · zoom · gupshup · positus · serpro · botmaker_v1 (sem assinatura nativa — ver WEBHOOK_REQUIRE_SIGNATURE).
Specs de credenciais por broker em config_specs.py (dirige o formulário do console). Mensagens ricas (menu/lista/botões) com fallback texto numerado para canais sem suporte.
12. Voz e vídeo (LiveKit + callbridge)
- LiveKit (SFU): voz/vídeo do widget. Sala tenant:conversa; token JWT curto via POST /api/call/token. Portas 7880 (ws) / 7881 (ICE TCP) / 7882 udp. Sem LIVEKIT_URL → recurso desligado (503). Gravação via Egress → MinIO (CALL_RECORDING, off por padrão — LGPD).
- callbridge (app/callbridge.py, processo próprio): ponte WebRTC (aiortc) das chamadas nativas WhatsApp (Meta Calling API) — termina SRTP/Opus e ponteia o áudio para a sala LiveKit. Comandado por Redis pub/sub (callbridge:cmd). SINGLE-REPLICA por design (dono de todos os RTCPeerConnection) — não escalar. Duração gravada em chamada_log (faturamento por minuto).
13. Frontend (console e widget)
Console (frontend/, v0.1.59)
- React 18.3 + Vite 5.4 + TS 5.5; CSS puro com design tokens (sem framework); React Flow (editor de fluxo) + TipTap (editor rico); hooks próprios de dados com polling (ex.: Atendimento a cada 4 s) — sem WebSocket no console.
- Telas: Início (KPIs) · Atendimento (inbox 3 colunas + copiloto) · Supervisão · Filas/FilaConfig · Contatos · Canais · WidgetCustomizer (prévia ao vivo) · Webhooks · Avisos (notificações e-mail à equipe) · Painéis (dashboards no-code) · Administração (acesso/comercial) · Clientes & tenants · Assistentes/AssistenteEditor · Base (RAG) · Intenções · Entidades · Fluxos (editor + simulador) · Login.
- Guards de rota por papel (agente/supervisor/admin); chamadas sempre com X-Platform-Token + Bearer.
Widget do cliente final (frontend/public/widget.js)
- Script embarcável: <script src=".../widget.js" data-tenant data-channel data-api async>. Envia por HTTP (POST /webhook/{tenant}/{broker}), recebe por WebSocket /ws (único WS do produto). uid persistente por canal no localStorage. Voz/vídeo LiveKit (SDK servido estático junto ao widget). widget-embed.html = página de prévia (anti-DOM-XSS: rejeita ?api cross-origin).
Build
Multi-stage node:22-alpine → nginx:1.27-alpine; dist copiado na raiz e sob /app/v1/omnichannel-platform (HML). nginx template (envsubst): SPA fallback, proxy /api|/webhook|/chat|/ws|/auth com DNS lazy, WS com read_timeout 3600s, client_max_body_size 25m.
14. Infraestrutura e deploy
docker-compose (dev — infra/docker-compose.yml, project plataforma)
postgres (pgvector/pg16, max_connections=400) · redis 7 (AOF everysec) · minio (:9001 console) · api (:8000, UVICORN_WORKERS=2) · web (nginx, :8088) · worker · callbridge · nlu · livekit v1.13.3 (--dev) · keycloak 26 (:8083, realm importado) · perfis: tunel(ngrok)/tunel-cf · tools (pgAdmin :8082, redis-commander :8081) · front (Vite HMR :5176) · observ (Prometheus :9090 + Grafana :3000 com provisioning versionado).
Kubernetes (infra/k8s/, manifests crus)
namespace · ConfigMap/Secret · api: Deployment 2 réplicas + Service + HPA CPU 2→10 (requests 100m/256Mi, limits 1cpu/512Mi) · worker: 2 réplicas + HPA 2→12 · nlu: 1 réplica · ingress nginx + cert-manager (proxy-body-size 16m). API e worker usam a mesma imagem (muda o command); NLU tem imagem própria.
Keycloak (realm, papéis e service account)
Realm plataforma (em dev, importado no boot de infra/keycloak/realm-plataforma.json) · roles de realm agente/supervisor/admin (+ super_admin p/ control-plane) · clients console (público, ROPC + PKCE S256) e plataforma-verify (confidencial, OIDC do cliente final) · mapper tenant_id no access token — obrigatório com TENANT_ISOLATION_ENFORCE · client de admin confidencial com service account e as 4 roles de realm-management (manage-users, view-users, query-users, view-realm): sem elas a tela Administração › Usuários toma 403 na Admin API, que a plataforma traduz em 502 · KC 24+: tenant_id é atributo unmanaged e o realm o descarta em silêncio se Unmanaged attributes estiver Disabled — a listagem de usuários volta vazia sem erro. Passo a passo, validação e troubleshooting: docs/KEYCLOAK-SETUP.md.
CI/CD
GitLab tag → job release do GitLab CI → PipelineRun Tekton omnichannel-release-pipeline → registry. O SHA da tag é clonado uma vez e gera as imagens phg/plataforma-omnichannel/{app|api|nlu} com a mesma tag imutável. As Tasks e a Pipeline ficam no repositório centralit-cicd; o disparador fica em .gitlab-ci.yml. Homologação: <host-de-homologacao>.
Modos de entrega
SaaS ✅ (padrão) · Multi/revenda 🟡 (falta papel revendedor + billing agregado) · On-Premise ✅ (roteiros em docs/instalacao/ — Docker Compose homologado e anexo Kubernetes/GitOps; licença assinada localmente; recursos degradam sem quebrar: voz/SMTP/IA off).
15. Segurança
- Trava de boot em produção: verificar_seguranca() roda no lifespan da API e no main do worker — em hml/prod, o serviço se recusa a subir se: PLATFORM_TOKEN for o token padrão de desenvolvimento (<token-de-dev>)/vazio, INTEGRATIONS_SECRET_KEY vazio (Fernet das credenciais de integração), AUTH_LINK_SECRET vazio (links de auth do cliente).
- Flags de produção: TENANT_ISOLATION_ENFORCE=true (claim tenant_id ↔ tenant), WEBHOOK_REQUIRE_SIGNATURE=true (recusa webhook sem assinatura — fecha o Botmaker sem HMAC nativo), SIM_ENABLED=false (endpoints de simulação nem montam).
- Anti-SSRF: allowlist para download de anexos (ALLOWED_ATTACHMENT_HOSTS) e crawler da KB; nós HTTP/webhook do fluxo idem.
- Credenciais de canal/integração cifradas (Fernet); webhook LiveKit assinado (JWT + sha256 do corpo); IDOR cross-tenant travado nas chamadas (_checar_tenant).
- CORS * com allow_credentials=false (widget em qualquer site; auth via header).
- LGPD: gravação de chamadas off por default; CSAT/contexto no tenant isolado; auditoria administrativa (admin_audit_log).
16. Capacidade e escala
Números medidos (docs CAPACIDADE.md + bench/):
- 4M msg/mês = 1,54 msg/s média (~15 pico) → usa ~1% de 1 réplica NLU (160 req/s medidos); folga ~100× média / ~10× pico.
- Load test real (1 host): ingestão ~340 rps (100k conversas, 0,012% erro); motor ~175 conversas/s com 4 réplicas de worker (~44/s por réplica, linear); 161/400 conexões PG no pico; 100k conversas paradas em handoff = custo ~zero.
- Modelo p/ 100k usuários simultâneos ativos (3.333 msg/s): ~76 réplicas de worker + API atrás de LB + PgBouncer (transaction pooling — código já compatível).
- Escala: NLU stateless (+160 rps/réplica), workers stateless, WS via Redis pub/sub; callbridge é a única peça single-replica.
17. Testes
- Backend: 34 arquivos, ~364 testes (backend/tests/), integração contra o stack vivo via backend/run-tests.sh (sobe o compose, roda pytest em container efêmero). Destaques: test_multitenant (isolamento), test_rbac_full, test_dead_letter, test_debounce_logic, test_flow_*, test_timeout*, test_encryption_full, brokers (contract/routing).
- E2E: 30 specs Cypress (frontend/cypress/e2e/): atendimento (incl. carga), widget (incl. F5/reconexão), chamada, supervisão, filas, RBAC, tenant, painéis… Runners: local (run-e2e.sh, na rede do compose) e HML (run-e2e-hml.sh, subset UI-pura).
- CI não roda testes (stages comentados) — rodar local/manual antes de release (ver §19).
18. Migrações
Runner próprio por schema (core/migrations.py): 89 versões (LATEST=89; v1 baseline → v88 bloco_custom (catálogo de blocos do workspace) → v89 channel.padrao (qual conexão de IA é a padrão do workspace, antes era ordem alfabética)). Aplicação no startup de API e worker (provisioning.bootstrap() → migrate_all), com advisory lock por schema; registro em public.tenant_schema_migrations; rollback e status via python -m app.manage.
19. Dívida técnica e lacunas
Documentado mas NÃO implementado/versionado (não prometer como pronto):
- DR (pgBackRest/PITR/CronJob): RPO ≤5 min / RTO ≤30 min estão especificados em docs/disaster-recovery.md, mas não há CronJob, pgbackrest.conf nem scripts de backup no repo. Hoje o "backup" real versionado é AOF do Redis + volumes.
- callbridge e LiveKit em k8s: sem manifests (só compose) — chamadas de voz não estão cobertas no deploy k8s versionado.
- Separação de workers por fila (chat.fast/rag/llm): spec no k8s/README.md, não implementada.
- ulimits/nofile: nenhum ajuste de FD versionado (compose ou k8s), apesar da meta de carga alta.
- Testes no CI: ainda precisam ser adicionados como Tasks anteriores aos builds da pipeline Tekton.
Dívidas de código/organização:
- /metrics sem proteção no código (mitigar por rede).
- Métrica mensagens_total{direcao="saida"} declarada mas sem alimentação localizada no pipeline de emissão.
- Sem métrica de heartbeat para relay/sweepers (proxy: outbox_pendentes).
- Sem rate limiting no backend.
- Divergência de realm Keycloak em HML: disparos (frontend/Dockerfile) vs plataforma-omnichannel (run-e2e-hml.sh) vs plataforma (dev) — unificar.
- Multi/revenda e On-Premise parciais (§14); widget confia no user_id do localStorage (hardening HMAC pendente — TODO(sec)).
- Docstring do worker desatualizado ("3 workers"; são 4 filas consumidas).
20. Apêndices
A. Variáveis de ambiente essenciais (defaults)
Grupo | Variáveis |
|---|---|
Core | ENVIRONMENT=dev · ROOT_PATH=/api/v1/omnichannel-platform · LOG_LEVEL=INFO |
Banco/Redis | DATABASE_URL · DB_POOL_SIZE=10 · REDIS_URL · WS_CHANNEL=omnichannel:ws |
Filas | QUEUE_MAX_ATTEMPTS=5 · QUEUE_VISIBILITY_TIMEOUT=60 · WORKER_POLL_INTERVAL=0.5 · RELAY_BATCH=200 · WORKER_CONCURRENCY=5 |
Timeouts | HTTP_TIMEOUT=15 · LLM_TIMEOUT=60 · NLU_TIMEOUT=4 · DEBOUNCE_MS=0 |
Segurança (trava de boot) | PLATFORM_TOKEN · INTEGRATIONS_SECRET_KEY · AUTH_LINK_SECRET |
Segurança (flags) | TENANT_ISOLATION_ENFORCE=false→true · WEBHOOK_REQUIRE_SIGNATURE=f… · SIM_ENABLED=false · ALLOWED_ATTACHMENT_HOSTS |
Keycloak | KEYCLOAK_JWKS_URL · KEYCLOAK_ISSUERS · KEYCLOAK_CLIENT_ID · KEYCLOAK_ADMIN_* |
Atendimento | INATIVIDADE_SWEEP_SEG=20 · PRESENCA_TIMEOUT_SEG=180 · PRESENCA_SAINDO_CARENCIA_SEG=45 · PRESENCA_WS_TICK_SEG=15 · CONTINUAR_CROSS_CANAL=true (48 h) |
Voz | LIVEKIT_URL · LIVEKIT_INTERNAL_URL · LIVEKIT_API_KEY/SECRET · CALL_RECORDING=false |
NLU/Obs | NLU_URL=http://nlu:8001 · WORKER_METRICS_PORT=9100 · OTEL_EXPORTER_OTLP_ENDPOINT (opcional) |
B. Comandos úteis
# Stack completo dev
cd infra && docker compose up --build # console :8088 · api :8000 · keycloak :8083
docker compose --profile observ up -d # Prometheus :9090 + Grafana :3000
docker compose --profile tools up -d # pgAdmin :8082 · redis-commander :8081
# Testes
./backend/run-tests.sh # integração (stack vivo)
./frontend/run-e2e.sh # Cypress local
# Operação
curl :8000/health/ready # readiness API (DB+Redis)
curl :9100/health/ready # readiness worker
GET /api/filas # profundidade das filas + outbox
GET /api/admin/dead-letter # jobs esgotados
POST /api/filas/reprocessar # replay dos failed
python -m app.manage status-all # status de migração por tenantFontes
Documento consolidado da análise do código (commit e33494b), da documentação do repositório (PROJETO.md, MOTOR-FLUXO.md, ATENDIMENTO-HUMANO.md, CAPACIDADE.md, NLU-BENCHMARK.md, INSTALL-*, disaster-recovery.md) e dos benchmarks versionados (bench/nlu, bench/load).