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)

URLs de Producao

Servico	URL
Hub (Central)	https://pontifex.infraifd.com/hub/
Playground	https://pontifex.infraifd.com/playground/
API Docs	https://pontifex.infraifd.com/docs
Documentacao	https://pontifex-docs.infraifd.com
Chatwoot	https://chatwoot-rails.infraifd.com

Credenciais Hub/Playground: admin / Primavera2@

Quick Start

1. Configurar Credenciais

mkdir -p .secrets
cat > .secrets/credentials.toml << 'EOF'
[openai]
api_key = "sk-proj-SUA-CHAVE-OPENAI"

[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

3.1 Criar conta admin

1. Acesse no navegador: http://SEU_IP:3000
2. Clique em Create New Account
3. Preencha: Full Name, Email, Password, Account Name (ex: Instituto FD)
4. Clique em Sign Up

3.2 Criar API Channel Inbox

1. Na barra lateral esquerda, clique no icone de engrenagem (Settings)
2. Clique em Inboxes > botao "+ Add Inbox" (canto superior direito)
3. Na tela "Choose a channel", selecione API (icone { })
4. Preencha:
5. Channel Name: Pontifex Bot
6. Webhook URL: http://pontifex-api:8000/webhooks/chatwoot
7. Clique em Create API Channel
8. Adicione seu usuario admin como agente e clique em Add Agents
9. Anote o Inbox ID — visivel na URL: .../inboxes/X/settings (o X e o ID)

A Webhook URL usa o nome do container Docker (pontifex-api), nao localhost.

3.3 Obter API Access Token

1. Na barra lateral esquerda, clique no seu avatar (canto inferior esquerdo)
2. Clique em Profile Settings
3. Role ate a secao "Access Token"
4. Copie o token e cole no campo api_token do credentials.toml

3.4 Reiniciar Pontifex API

docker compose -f docker-compose.production.yml restart pontifex-api

Para o guia completo com mais detalhes, veja CHATWOOT_SETUP.md

4. Testar

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

Arquitetura

┌──────────────────────────────────────────────────────────────────────────┐
│                           Docker Network                                 │
│                                                                          │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐                │
│  │   Chatwoot   │───>│  Pontifex IA │───>│   OpenAI     │                │
│  │    :3000     │<───│     :8000    │    │   (GPT-4o)   │                │
│  └──────────────┘    └──────────────┘    └──────────────┘                │
│         │                   │                                            │
│         v                   v                                            │
│  ┌──────────────┐    ┌──────────────┐                                    │
│  │  PostgreSQL  │    │  MkDocs/Docs │                                    │
│  │    :5432     │    │    :8000     │                                    │
│  └──────────────┘    └──────────────┘                                    │
│         │                                                                │
│  ┌──────────────┐                                                        │
│  │    Redis     │                                                        │
│  │    :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 GPT-4o (OpenAI)
         │
         v
5. Resposta enviada via API do Chatwoot
         │
         v
6. Cliente recebe resposta

Handoff para Humano

Quando o agente inclui [HANDOFF] na resposta:

1. Marcador e removido da mensagem
2. Conversa muda para status open
3. Atendente humano ve na fila
4. Agente para de responder automaticamente

Variaveis de Ambiente

Obrigatorias

Variavel	Descricao
openai.api_key	Chave de API da OpenAI (GPT-4o)
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

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