📐 Documentação técnica

Sumário

OminiConnect — Arquitetura do Ecossistema

Esta é a documentação técnica de como o sistema funciona internamente.

Para visão de produto, ver README.md. Para regras, ver RULES_AND_POLICIES.md.

Visão geral

OminiConnect é um SaaS multi-tenant de prospecção e CRM, composto por 9 agents autônomos que cooperam via eventos compartilhados (Postgres + filas em-memória + HTTP interno).

                   ┌──────────────────────────────────────────────┐
                   │                  CANAIS                      │
                   │  WhatsApp · E-mail · Voice · Manual          │
                   └─────────┬───────────────────┬────────────────┘
                             │                   │
                             ▼                   ▼
       ┌─────────────────────────────┐  ┌─────────────────────────┐
       │  💬 WhatsApp Engine          │  │  📤 Cold Email Sender    │
       │  (Baileys + Intent + LLM)    │  │  (SMTP + pixel + click)  │
       └────────┬─────────────────────┘  └──────────┬──────────────┘
                │                                    │
                │  /bot/flow-trigger                 │  /me/cold-email/send
                ▼                                    ▼
       ┌──────────────────────────────────────────────────────────┐
       │              🌐 API Backend (FastAPI)                    │
       │  · Autenticação, multi-tenant, tracking, webhooks         │
       │  · Phone Reality · Email Reality                          │
       │  · /admin/agents/overview (observabilidade unificada)     │
       └─────────┬──────────────────────────────┬──────────────────┘
                 │                              │
                 ▼                              ▼
       ┌─────────────────────┐         ┌─────────────────────────┐
       │  📊 CRM Auto-Move    │         │  📬 Email Inbox IA       │
       │  (poll 5min)        │         │  (IMAP poll 60s)        │
       └─────────────────────┘         └─────────────────────────┘
                 │                              │
                 └──────────┬───────────────────┘
                            ▼
       ┌──────────────────────────────────────────────────────────┐
       │   🛡 Sales Sentinel  ·  🛡📧 Email Sentinel               │
       │   Monitoram tudo · pausam o que tá ruim · auto-heal      │
       └──────────────────────────────────────────────────────────┘

Os 9 agents

1. 💬 WhatsApp Engine (omini_engine)

2. 🌐 API Backend (evolution_ominiconnect)

3. 🛡 Sales Sentinel (sales_sentinel)

4. 📊 CRM Auto-Move (crm_auto_move_worker)

5. 🎙 Voice Outreach (voice_outreach_worker)

6. 📤 Cold Email Sender (cold_email_worker)

7. 📬 Email Inbox IA (email_inbox_worker)

8. 🛡📧 Email Sentinel (email_sentinel)

9. 🧠 LLM Router (evolution_llm_router)

Arquitetura de produto (3 telas)

O sistema de outbound tem 3 telas com papéis bem definidos:

📡 Caça-Leads (gerador)
   ↓ leads.email, leads.phone, leads.cnpj_data preenchidos
🚀 Outbound Hub (disparador)
   ↓ campanhas-irmãs em N canais
📋 CRM (acionamento individual)
   ↓ manual / bulk / Sales Agent IA

📡 Caça-Leads — gerador oficial

Fonte primária de leads. Captura por nicho/cidade, gera dossiê comercial, enriquece automaticamente (email_enricher do website + BrasilAPI do CNPJ). Cria leads em omini.leads com source='leadgen_scrape'.

🚀 Outbound Hub — disparador unificado

Tela única /outbound agregando campanhas dos 3 canais via VIEW omini.v_outbound_campaigns.

Estratégia de canais (você decide o risco):

Canal Risco em frio Comportamento
📧 E-mail ✅ Seguro LGPD B2B (Art. 7º IX). Pré-marcado, recomendado.
🎙 Voice TTS 🟡 Médio Cap LOCKED 5/dia. Warning visual.
💬 WhatsApp 🔴 Alto Warning vermelho explícito. Disparado mesmo assim se user escolher.

Princípio: avisar, não impedir. O usuário é informado dos riscos via UI, tutorial e RULES_AND_POLICIES.md (Regra #19), mas o sistema executa a vontade dele. Sales Sentinel monitora e pausa em casos críticos.

📋 CRM — acionamentos individuais

Pipeline Kanban. Cada card de lead permite:

Fluxos canônicos

Fluxo 1: Outbound WhatsApp (Caça-Leads)

1. User cria campanha em /leadgen
2. Backend scrape Google Maps + enriquece (BrasilAPI CNPJ)
3. Lead criado com source='leadgen_scrape', deal em stage 'Lead'
4. User aciona Sales Agent IA (bulk ou single)
5. Phone Reality valida número
6. Engine envia 1ª mensagem com roteiro renderizado
7. Lead responde → Engine classifica intent → resposta personalizada
8. CRM Auto-Move avalia → deal sobe pra 'EmContato'
9. Conversa evolui → deal sobe stages → fecha em 'Fechado' ou 'Perdido'

Fluxo 2: Cold Email + Handoff WhatsApp

1. User cadastra conta SMTP/IMAP em /cold-email
2. User cria campanha (template, niche, daily_cap, window)
3. Cold Email Sender envia respeitando cap + window
4. Email Reality filtra inválidos antes
5. Pixel mede open / redirect mede click / IMAP detecta reply
6. Lead clica CTA WhatsApp → Engine recebe msg
7. Email Inbox IA marca lead como 'engaged' / clicked_wa=true
8. Engine assume conversa com contexto completo (email_context_summary no system_prompt)
9. CRM unifica: 1 deal, múltiplos canais visíveis em /me/leads/{id}/email-thread

Fluxo 3: Inbound WhatsApp (orgânico)

1. Pessoa manda WhatsApp do nada (viu Instagram, indicação, anúncio)
2. Engine recebe → chama /bot/flow-trigger com sender_pn + push_name
3. Backend: Phone Reality valida real (não broadcast/group/lid)
4. Não existe lead pra esse phone → cria com source='inbound_whatsapp', score=75
5. Cria contato CRM + deal stage 'Lead'
6. Flows com trigger='first_contact' disparam
7. Engine assume conversa com IA
8. Mesmo fluxo de qualificação do Fluxo 1 daí em diante

Fluxo 4: Sentinel detecta problema

1. Email Sentinel calcula bounce_rate da campanha X = 12%
2. Avalia regra: 12% > 8% threshold critical
3. Update campanha: status='paused', paused_by_sentinel_at=NOW(), paused_reason='high_bounce'
4. Insert alert: severity='critical', code='EMAIL_BOUNCE_HIGH', action_taken='auto_pause'
5. Admin abre /agent-observability → vê o agent 'email_sentinel' em warning
6. Timeline mostra o alert + ação taken
7. Admin investiga / corrige template / reativa manualmente OU espera self-heal

Marketing site → vendas integradas

O landing público (/landing) é parte do funil — não é só "página institucional".

Pontos de captura:

Endpoint público: POST /api/public/lead-capture-demo

  1. INSERT em omini.leads (user_id=1, source='website_landing', score=80)
  2. INSERT em crm_deals (pipeline default, stage='Lead', notes com UTM + magnet)
  3. Dispara e-mail welcome via SMTP do sistema (📧 Sistema · Hostinger)
  4. Notifica admin via OminiComms feed

Pós-captura: admin pode rodar campanha de nurturing no Outbound Hub filtrando source='website_landing'.

Bancos de dados

Postgres evolution

Redis

Deploy

Git-based deploy via post-receive hook em /srv/omini-prod.git:

  1. git push origin main (do dev local OU do /srv/omini-prod/)
  2. Hook valida GATE 1 (JS node --check em scripts inline) + GATE 2 (py_compile)
  3. Reseta working tree em /srv/omini-prod/
  4. Copia arquivos pra runtime (/opt/evolution/scripts/, /opt/omini-engine/src/, /var/www/saas/)
  5. Build engine TypeScript + docker cp dist → omini_engine
  6. Restart granular dos containers afetados (não restarta tudo)

Detalhes em CLAUDE.md e CICD_PIPELINE.md.

Observabilidade

Política de segurança

Ver RULES_AND_POLICIES.md — 18 regras invioláveis cobrindo:

Última revisão: Maio 2026 — v2.1

Esta documentação reflete o sistema em produção em luizrjesus.app.br.
Para regras invioláveis, ver Termos. Para dados pessoais, ver Privacidade.