---
title: Documentação Técnica
slug: aura/documentacao-tecnica
createdAt: 2026-11-19T14:33:14.916Z
---

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

```javascript
 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:**

1. **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).
2. **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

```javascript
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\_:::Iframe{code="<hex>"}

::: (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):**

1. **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.
2. **callbridge e LiveKit em k8s:** sem manifests (só compose) — chamadas de voz não estão cobertas no deploy k8s versionado.
3. **Separação de workers por fila** (chat.fast/rag/llm): spec no `k8s/README.md`, não implementada.
4. **ulimits/nofile:** nenhum ajuste de FD versionado (compose ou k8s), apesar da meta de carga alta.
5. **Testes no CI:** ainda precisam ser adicionados como Tasks anteriores aos builds da pipeline Tekton.

**Dívidas de código/organização:**

1. `/metrics` sem proteção no código (mitigar por rede).
2. Métrica `mensagens_total{direcao="saida"}` declarada mas sem alimentação localizada no pipeline de emissão.
3. Sem métrica de heartbeat para relay/sweepers (proxy: `outbox_pendentes`).
4. Sem rate limiting no backend.
5. **Divergência de realm Keycloak em HML:** `disparos` (frontend/Dockerfile) vs `plataforma-omnichannel` (run-e2e-hml.sh) vs `plataforma` (dev) — unificar.
6. Multi/revenda e On-Premise parciais (§14); widget confia no `user_id` do localStorage (hardening HMAC pendente — `TODO(sec)`).
7. 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

```javascript
# 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 tenant
```

## Fontes

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`).
