Arquitetura Geral¶

Visao Macro¶

Text Only

                    +-------------------------+
                    | Operador (cliente Highlas) |
                    +-----------+-------------+
                                |
                  HTTPS via Nginx + Cloudflare
                                |
        +-----------------------+-----------------------+
        |                                               |
+-------v---------+                              +------v---------+
|  Frontend       |                              |  Backend        |
|  Next.js 15     |  ----- REST /api/v1/ ----->  |  Django 5.2     |
|  React 19       |  <----  JSON responses ----  |  DRF + Channels |
|  TypeScript     |                              |  Daphne (ASGI)  |
+-----------------+                              +--+----+----+----+
                                                    |    |    |
                                                    |    |    |
                +-----------------------------------+    |    +---------------+
                |                                        |                    |
        +-------v-----+                          +-------v------+      +------v---------+
        |  PostgreSQL |                          |  Redis 7     |      | Celery Workers |
        |  16 (data)  |                          |  (broker +   |      | + Celery Beat  |
        |             |                          |   channels)  |      | (scheduler)    |
        +-------------+                          +--------------+      +-------+--------+
                                                                              |
                                                              tarefas async   |
                                                                              |
                                                                              v
                                                                      +-------+--------+
                                                                      | Meta WhatsApp  |
                                                                      | Cloud API v22  |
                                                                      | (graph.fb.com) |
                                                                      +-------+--------+
                                                                              |
                                                                              | webhook
                                                                              v
                                                                      +-------+--------+
                                                                      |   Cliente      |
                                                                      |   final        |
                                                                      |   (WhatsApp)   |
                                                                      +----------------+

Componentes¶

Backend - Django 5.2 + DRF¶

Apps principais:

App	Responsabilidade
`core`	Models base (`TimeStampedModel`), paginacao customizada
`contacts`	CRUD de contatos e grupos
`surveys`	Definicao de pesquisas, perguntas, condicionais
`responses`	Execucoes (`SurveyRun`), respostas (`SurveyAnswer`), tarefas Celery
`whatsapp`	Webhooks, servicos Meta Graph API, `MessageLog`
`chat`	Chat livre operador-cliente, WebSockets para tempo real
`users`	Gestao de usuarios e permissoes

Stack: - Django 5.2.6 - framework principal - DRF 3.16.1 - APIs REST - Daphne - servidor ASGI (suporta WebSockets via Channels) - Channels 4 - WebSockets para chat em tempo real - SimpleJWT - autenticacao via JWT - Celery 5.5 - tarefas assincronas - django-celery-beat - scheduler de tarefas periodicas - drf-spectacular - geracao de OpenAPI/Swagger

Frontend - Next.js 15¶

Estrutura:

Text Only

frontend/src/
├── app/                  # App Router (Next.js 15)
├── components/
│   ├── ui/              # Components atomicos (Button, Card, etc)
│   ├── contacts/        # Gestao de contatos
│   ├── surveys/         # Editor de pesquisas
│   ├── runs/            # Execucoes de pesquisas
│   ├── messages/        # Chat livre + visualizacao de conversas
│   └── analytics/       # Dashboards
├── lib/
│   ├── api.ts           # Cliente axios + endpoints
│   ├── toast.ts         # Notificacoes
│   └── ...
├── hooks/               # Custom hooks (TanStack Query, WebSocket)
├── contexts/            # Auth, Navigation
└── types/               # TypeScript types

Stack: - Next.js 15.5 (App Router, standalone build) - React 19 - TypeScript strict mode - Tailwind CSS + shadcn/ui components - TanStack Query para fetching e cache - react-toastify para notificacoes - lucide-react para icones

Servicos de Apoio¶

PostgreSQL 16 - banco principal (porta 5433 externa, 5432 interna)
Redis 7 - broker do Celery + channel layers do Django Channels (DB 2)
Nginx (host) - reverse proxy + SSL via Let's Encrypt
MkDocs - documentacao publica em /docs

Servico Externo¶

Meta WhatsApp Business Cloud API v22.0 - https://graph.facebook.com/v22.0/
Phone Number ID: configurado em META_PHONE_NUMBER_ID
Business Account ID: META_BUSINESS_ID
Token: META_ACCESS_TOKEN (~60 dias de validade, renovar antes de expirar)

Fluxos Principais¶

Fluxo 1: Disparar pesquisa para contatos¶

Text Only

[Operador clica "Nova Execucao"]
       |
[Selecione pesquisa + contatos/grupos]
       |
[POST /api/v1/surveys/{id}/start_survey/]
       |
       v
[Backend: para cada contato]
       |
       +-> Ja tem run ativa? -> sim+expirada => auto-heal
       |                       -> sim+valida => bloqueia
       |                       -> nao => cria run
       |
       +-> Envia template via Meta API
       |
       +-> Se sucesso: sent_at = now()
       |
       v
[Cliente recebe template no WhatsApp]

Fluxo 2: Cliente responde¶

Text Only

[Cliente envia mensagem no WhatsApp]
       |
       v
[Meta envia webhook POST /api/v1/webhook/meta/]
       |
       +-> Valida verify_token (GET) ou processa msg (POST)
       +-> find_contact_by_phone() (tolera "9" do BR)
       +-> Cria MessageLog com source=survey ou chat
       |
       +-> Tem SurveyRun ativa?
       |   |
       |   +-> SIM:
       |   |   +-> active_run.touch_activity()
       |   |   +-> survey_service processa resposta
       |   |   +-> Avanca para proxima pergunta OU finaliza
       |   |
       |   +-> NAO:
       |       +-> chat_service registra como conversa livre
       |
       v
[Bot envia proxima pergunta via Meta API]

Fluxo 3: Expiracao automatica¶

Text Only

[Celery Beat: a cada 1h]
       |
       v
[Task expire_stale_runs]
       |
       +-> Regra A: pending sem sent_at > 24h
       +-> Regra B: pending com sent_at > 72h
       +-> Regra C: in_progress sem activity > 24h
       |
       +-> Bulk update status = 'expired', completed_at = now()
       |
       v
[Runs liberadas para reenvio futuro]

Deploy¶

Producao (cliente Highlas)¶

URL: https://highlasdobrasil.com.br
Servidor: VPS Hostinger (Linux)
Branch: main
Banco: PostgreSQL no proprio container (volume postgres_data)

Staging¶

URL: mesma https://highlasdobrasil.com.br durante validacoes
Branch: staging
Banco: mesmo do producao (cuidado!)

Idealmente, staging deveria ter URL e banco separados. Hoje compartilham recursos. Vide roadmap-gaps.md#decisoes-arquiteturais-pendentes.

Comando para subir tudo¶

Bash
cd /home/ubuntu/projetos/chat_bot_evolution_drf
docker compose up -d

Comando para atualizar (rebuild + migrate)¶

Bash
git pull origin staging  # ou develop
docker compose build backend frontend
docker compose up -d --force-recreate backend frontend celery_worker celery_beat
docker compose exec backend python manage.py migrate

Comando para ver logs¶

Bash
docker compose logs -f backend         # tempo real
docker compose logs backend --tail 50  # ultimas 50 linhas

Convencoes Importantes¶

Variaveis de Ambiente¶

Todas as configuracoes sensiveis sao lidas via python-decouple de backend/.env:

SECRET_KEY (obrigatorio, sem default inseguro)
DEBUG=False em producao
ALLOWED_HOSTS, CORS_ALLOWED_ORIGINS, CSRF_TRUSTED_ORIGINS
META_ACCESS_TOKEN, META_PHONE_NUMBER_ID, META_BUSINESS_ID
SURVEY_EXPIRY_* (configuracoes de expiracao)

Sempre que adicionar nova variavel, atualizar tambem .env.example.

Timezone¶

Banco armazena em UTC. Display em America/Sao_Paulo. Configurado em settings.py: TIME_ZONE = 'America/Sao_Paulo'.

Convencoes de Codigo¶

Vide CLAUDE.md na raiz do projeto para padroes detalhados de Python, TypeScript, testes, etc.

Versionamento¶

Backend: Django migrations sequenciais por app
Frontend: build standalone Next.js (sem versionamento de bundle visivel)
API: /api/v1/ (planejamento de v2 vide roadmap)

Observabilidade¶

Logs¶

Backend: backend/logs/ (rotacao 10MB, 5 backups)
Container: docker compose logs <service>
Celery worker: logs especificos via docker compose logs celery_worker

Metricas¶

Hoje minimas. Roadmap inclui adicao de Prometheus + Grafana (vide roadmap-gaps).

Health Checks¶

chatbot_docs: tem healthcheck (HTTP 8000)
chatbot_postgres: pg_isready a cada 30s
Demais: nao tem healthcheck configurado

Dependencias Externas Criticas¶

Servico	Impacto se cair
Meta Graph API	Nao envia mensagens, nao recebe webhooks
PostgreSQL	Aplicacao para
Redis	Celery para de processar, WebSockets caem
Nginx (host)	URL publica indisponivel
Let's Encrypt	SSL expira em 90 dias, renovacao automatica via certbot