# Como construímos um motor multi-tenant de agentes em Clojure com Pathom 3 e Aeron IPC para operar com latência sub-milissegundo

> **Artigo Técnico de Engenharia**  
> **Autor:** Patrick Serrano — Principal Engineer & Fundador da PCMS Engenharia de Software  
> **Data:** 14 de outubro de 2026  
> **Tags:** #Clojure #Pathom3 #AeronIPC #RAG #HighPerformance #SoftwareArchitecture

---

## O Desafio: Além dos Chatbots de Arrasta-e-Solta

A imensa maioria dos chatbots de WhatsApp disponíveis no mercado brasileiro hoje é montada com stacks frágeis: fluxogramas no n8n ou Typebot conectados a chamadas REST desestruturadas para endpoints do OpenAI. 

Quando você opera no setor de saúde (clínicas médicas, odontológicas, laboratórios), essa abordagem desmorona rapidamente por três motivos:
1. **Latência imprevisível e timeouts no webhook do WhatsApp:** Respostas lentas geram cancelamento de mensagens e duplicidade de requisições.
2. **Ausência de isolamento multi-tenant real:** Filtrar tenant via cláusula `WHERE tenant_id = 'x'` em um banco compartilhado é um acidente de vazamento de dados à espera de acontecer.
3. **Falta de determinismo e auditabilidade:** É impossível auditar a árvore de decisões que levou um LLM a responder um determinado preço ou procedimento.

Para resolver isso, desenhamos a **Rohana** como um motor multi-tenant de alta performance construído em **Clojure**, orquestrado por um grafo de atributos via **Pathom 3** e interconectado por um barramento de eventos de memória mapeada com **Aeron IPC**.

Aqui está o bastidor de como essa arquitetura opera.

---

## 1. O Barramento de Eventos: Aeron IPC com Media Driver Embutido

Em vez de subir brokers pesados como RabbitMQ ou Kafka (que consom gigabytes de RAM e adicionam saltos TCP desnecessários em uma VPS única), integramos o **Aeron IPC** (`rohana.infra.aeron`) diretamente no processo JVM da engine.

O Aeron utiliza buffers circulares em memória compartilhada mapeada em arquivo (memory-mapped files / *ring buffers* off-heap):
- **Throughput:** Capaz de processar dezenas de milhões de mensagens por segundo entre threads com latência na casa dos microssegundos.
- **Isolamento de canais:** Canais lógicos organizados hierarquicamente por tenant:
  - `messages.incoming.<tenant>`
  - `messages.outgoing.<tenant>`
  - `audit.operational.<tenant>`
- **Desacoplamento total do Webhook:** O endpoint HTTP (`http-kit`) recebe a requisição do WhatsApp/Telegram, valida a assinatura HMAC em nanossegundos, grava o payload bruto no stream do Aeron e devolve imediatamente um HTTP `200 OK` para o servidor da Meta. Se o processamento do LLM levar 2 segundos ou se a conexão externa oscilar, a Meta nunca recebe timeout.

```clojure
;; Publicação ultra-rápida no Aeron IPC
(aeron/publish! bus (str "messages.incoming." (name tenant-id))
                {:msg/text       text
                 :channel/id     channel-id
                 :audit/event-id (str (java.util.UUID/randomUUID))})
```

---

## 2. Orquestração via Pathom 3: Grafos Declarativos EQL

Esqueça `if/else` aninhados ou máquinas de estado engessadas. A tomada de decisão na Rohana é baseada em **Pathom 3**, um orquestrador de resolução de grafos orientado a atributos (EQL — EDN Query Language).

No Pathom 3, cada capacidade do sistema é um *resolver* puro:
- `:tenant/id` + `:msg/text` ➔ `:tenant/config` (`rohana.resolvers.tenant`)
- `:msg/text` ➔ `:intent/type` (`rohana.resolvers.intent`)
- `:msg/text` ➔ `:presidio/scrubbed-text` (`rohana.infra.presidio`)
- `:rag/query` ➔ `:rag/sources` (`rohana.resolvers.rag`)
- `:guardrail/input` ➔ `:guardrail/status` (`rohana.resolvers.guardrail`)
- `:llm/prompt` ➔ `:llm/response` (`rohana.resolvers.llm`)

```clojure
(pco/defresolver rag-resolver
  "Recupera trechos do banco vetorial isolado apenas se a intenção exigir RAG."
  [env {:keys [tenant/id presidio/scrubbed-text intent/type]}]
  {::pco/output [:rag/sources :rag/grounded?]}
  (when (= type :faq)
    (let [query-expanded (rag/expand-query-pt-br scrubbed-text)
          matches        (turbovec/search env id query-expanded 5)]
      {:rag/sources   matches
       :rag/grounded? (seq matches)})))
```

### A mágica do Pathom:
1. **Resolução Lazy e Demanda Estrita:** Se uma mensagem é uma saudação inicial (`"Oi, boa tarde"`), o motor de inferência do Pathom percebe que a intenção não necessita de contexto vetorial e **nunca** executa a busca vetorial ou expansão de queries, economizando preciosos milissegundos e ciclos de computação.
2. **Zero Código para Novos Tenants:** Como a configuração do tenant é um dado puro (`resources/tenants/<id>.edn`), adicionar uma nova clínica ou escritório ao cluster exige apenas a escrita de um arquivo de dados EDN e a ingestão dos documentos correspondentes. Nenhum deploy de código é necessário.

---

## 3. RAG em Processo com TurboVec: Coleções Isoladas Fisicamente

Em vez de depender de um serviço externo que adicione saltos de rede para busca de similaridade de cossenos, integramos o **TurboVec** em processo:
- **Coleção por Tenant:** Cada tenant tem um diretório e um índice `IdMapIndex` completamente segregados no disco.
- **Fail-Closed em Leitura:** Toda busca valida o escopo de segurança da pasta. Se um payload não possuir a assinatura criptográfica e a marca de sanitização do gate de privacidade, ele é rejeitado antes de chegar ao prompt do LLM.
- **Expansão de Query Semântica pt-BR:** Para contornar limitações de embeddings em modelos multilíngues com vocabulário clínico brasileiro, aplicamos regras determinísticas de expansão de termos sinônimos (ex: *"clareamento"*, *"limpeza"*, *"profilaxia"*, *"aparelho ortodôntico"*), elevando nosso score de precisão de recuperação documental de **0.59** para **0.80** nos testes cegos.

---

## 4. O Impacto na Experiência do Cliente

Com essa arquitetura:
- O processamento interno da engine leva menos de **4 milissegundos** da recepção do webhook até o despacho para a inferência do LLM.
- O consumo de memória RAM do cluster inteiro é inferior a **512 MB**, rodando com folga em instâncias Oracle Cloud ARM.
- A trilha de auditoria é 100% reproduzível: para cada resposta dada no WhatsApp, temos o grafo exato de resolvers executados, os chunks recuperados e o hash do documento original.

Se você está construindo sistemas conversacionais corporativos, a regra é simples: trate fluxos como dados, isole o barramento da rede e transforme seu pipeline em um grafo declarativo.

A engenharia séria acontece nos bastidores.
