Documentacao de Infraestrutura

Guias de configuracao e deploy do Pontifex IA.

Guias Disponiveis

Documento	Descricao
CHATWOOT_SETUP.md	Configuracao completa do Chatwoot + Pontifex IA
DEPLOY.md	Deploy em producao (manual e GitHub Actions)

Quick Start

1. Configurar Credenciais

mkdir -p .secrets
cat > .secrets/credentials.toml << 'EOF'
[anthropic]
api_key = "sk-ant-api03-SUA-CHAVE"

[chatwoot]
api_url = "http://chatwoot-rails:3000"
api_token = "SEU_TOKEN"
account_id = 1
inbox_id = 1
EOF

2. Subir Servicos

# Criar volumes (primeira vez)
docker volume create chatwoot_postgres
docker volume create chatwoot_redis
docker volume create chatwoot_storage

# Inicializar banco (primeira vez)
docker compose -f docker-compose.production.yml up -d postgres redis
sleep 15
docker compose -f docker-compose.production.yml run --rm rails bundle exec rails db:chatwoot_prepare

# Subir tudo
docker compose -f docker-compose.production.yml up -d

3. Configurar Chatwoot

Acessar http://IP:3000
Criar conta admin
Criar API inbox com callback: http://pontifex-api:8000/webhooks/chatwoot
Copiar API token para credentials.toml
Reiniciar pontifex-api

4. Testar

curl http://localhost:8000/health
# {"status":"healthy"}

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                        Docker Network                        │
│                                                              │
│  ┌──────────────┐      ┌──────────────┐     ┌─────────────┐ │
│  │   Chatwoot   │─────>│  Pontifex IA │────>│  Anthropic  │ │
│  │    :3000     │<─────│     :8000    │     │   (Claude)  │ │
│  └──────────────┘      └──────────────┘     └─────────────┘ │
│         │                                                    │
│         v                                                    │
│  ┌──────────────┐      ┌──────────────┐                     │
│  │  PostgreSQL  │      │    Redis     │                     │
│  │    :5432     │      │    :6379     │                     │
│  └──────────────┘      └──────────────┘                     │
└─────────────────────────────────────────────────────────────┘

Fluxo de Mensagens

1. Cliente envia mensagem
         │
         v
2. Chatwoot recebe via canal (WhatsApp, Web, etc)
         │
         v
3. Webhook dispara para Pontifex IA
         │
         v
4. Pontifex processa com Claude (Anthropic)
         │
         v
5. Resposta enviada via API do Chatwoot
         │
         v
6. Cliente recebe resposta

Handoff para Humano

Quando o agente inclui [HANDOFF] na resposta:

Marcador e removido da mensagem
Conversa muda para status open
Atendente humano ve na fila
Agente para de responder automaticamente

Variaveis de Ambiente

Obrigatorias

Variavel	Descricao
`anthropic.api_key`	Chave de API da Anthropic
`chatwoot.api_url`	URL do Chatwoot
`chatwoot.api_token`	Token de acesso
`chatwoot.account_id`	ID da conta
`chatwoot.inbox_id`	ID do inbox

Opcionais

Variavel	Descricao
`chatwoot.webhook_secret`	Secret para validar webhooks
`chatwoot.human_team_id`	Time para handoff
`openai.api_key`	Chave OpenAI (fallback)

Troubleshooting Rapido

Problema	Solucao
Webhook nao recebido	Verificar URL no inbox API
Erro 401	Verificar api_token
Banco vazio	Rodar db:chatwoot_prepare
Resposta nao aparece	Verificar account_id e inbox_id