Negocia Platform V2 — Arquitetura Full-Stack (2026-05-08)

Cobrança inteligente via WhatsApp com IA. Webhook do Twilio entra no FastAPI, passa pelo Perception Layer (PII redact + Haiku 4.5 paralelo), e é roteado determinísticamente para o handler de estado. O fluxo NEGOTIATION roda hoje no caminho imperativo legacy por padrão; com a flag MIGRATE_NEGOTIATION_TO_LANGGRAPH=true o mesmo turno é executado pelo StateGraph LangGraph validado em prod (CREWAI_TO_LANGGRAPH Fase 1).

Edge / Ingress

LangGraph node

External SaaS

Datastore

Side-effect (caller)

Conditional edge

01 Topologia request → response

Ctrl/Cmd + scroll para zoom · arraste para pan · ⛶ abre em nova aba · 1:1 reseta · ↻ smart fit

Loading…

Caminho ativo em prod hoje Default em launch/v2: imperativo legacy. O flag MIGRATE_NEGOTIATION_TO_LANGGRAPH=true liga o StateGraph para mensagens em estado NEGOTIATION; rollback em ~50s via sed + force-recreate. Os 6 smoke tests reais (FAQ hit + planner_sonnet) confirmaram paridade comportamental antes da Fase 2 começar.

02 LangGraph Fase 1 · 9 nós · 2 conditional edges

Nó 1 · entry

perceive

Re-ingere o output do Perception Layer no estado do grafo. Idempotente por turno. Não chama LLM — apenas hidrata state.intent, state.sentiment, state.pii_clean_text.

stateless no LLM

Nó 2

domain_agent_run

CrewAI domain_agent ainda vivo como fallback natural. Roda em best-effort (templates ausentes não derrubam o turno). Será removido junto com crewai>=0.22.5 ao final das Fases 2-5.

crewai legacy best-effort

Nó 3

build_planner_ctx

Monta PlannerContext com last_template_presented, expected_inputs, is_deviation. É aqui que a heurística de desvio decide se o plano Sonnet vai ser convocado.

pydantic v2

Nó 4 · branch

faq_check

Consulta FaqRetrievalService contra Qdrant 1.15.5 (catálogo de 30 entries). Threshold real em prod = 0.60 (DESIGN tinha 0.85). Latência p50 ~290ms vs 3-4s do Sonnet.

qdrant conditional → 3 destinos

Nó 5 · branch

plan_sonnet

Chama negotiation_planner com Claude Sonnet 4.6. Retorna NegotiationResponse tipado. Falha → keep_domain_resp; sucesso → apply_plan_resp.

conditional → 2 destinos sonnet 4.6

Nó terminal

finalize_telemetry

Convergência única para END. Marca path_taken (faq · sonnet · domain), empilha spans Langfuse e libera o estado para o caller persistir + pós-processar fora do grafo.

audit v1.1 langfuse

03 Stack de dados · containers em produção

primary store

MongoDB 7.0

Database b2b_negotiation. Auth obrigatória habilitada (MELHORIA 1.4). Persiste contractor, debtor, negotiation, audit_log v1.1, message templates. Bind em 127.0.0.1:27017.

mongo:7.0 --auth

cache · locks · queue

Redis 7.2-alpine

AOF on, maxmemory 512mb, política allkeys-lru. Hospeda message_buffer, conversation locks, e a soft retry queue ZSET do PAYMENT_FLOW_E2E Phase C (worker via supervisor).

redis:7.2 aof + lru

vector · faq

Qdrant 1.15.5

Bump 1.12.4 → 1.15.5 em 2026-05-08 (AUDIT Action #7) silencia warning de skew com client 1.17.x e libera hybrid search nativo (sparse vectors). Volume qdrant_storage compatível sem migration.

qdrant:v1.15.5 1536d · cosine

vector · crm

Supabase pgvector

Projeto NEGOCIA SIMPLES (sa-east-1). Tabela debtor_interactions com HNSW index. Validado em prod 2026-05-06: crm_search_miss → write → crm_search_hit top_similarity=1.0.

pgvector hnsw 1536d

04 Integrações externas · SaaS

payments · pix + boleto

Asaas multi-tenant

MULTI_TENANT_ASAAS shipped 2026-05-03: _resolve_asaas_api_key + cross-check account_id no webhook. Cobranças PIX nascem na subconta do Contractor, não na conta master. Provisionamento automático (pix_key + webhook).

subaccount webhook token

payments · platform

Stripe

Billing da plataforma (assinatura SaaS para Contractors). Não passa por NEGOTIATION — flui pelo módulo services/payment/stripe.py isolado dos webhooks de cobrança.

platform-only

stt · audio

OpenAI Whisper

Modelo gpt-4o-mini-transcribe para transcrever áudios do WhatsApp antes do Perception Layer. OPENAI_API_KEY foi exposta no chat — alvo prioritário da rotação.

key rotation pending

llm · primary

Anthropic

Haiku 4.5 (claude-haiku-4-5-20251001) para perception + humanizer. Sonnet 4.6 (claude-sonnet-4-6) para o planner. Override em prod via DEFAULT_FAST_MODEL e DEFAULT_PLANNER_MODEL.

haiku 4.5 sonnet 4.6

05 Observabilidade · release tracking

tracing

Langfuse 4.5

Spans em cada nó do grafo (perceive · faq_check · plan_sonnet · finalize_telemetry). finalize_telemetry empilha o path_taken como score; golden suite empurra LLM-as-Judge scores no CI.

spans · scores

errors

Sentry

Release tracking via RELEASE_SHA injetado no build. Captura no FastAPI bootstrap; breadcrumbs incluem o conversation_id e contractor_id redactados.

RELEASE_SHA PII-aware

06 Infraestrutura · prod factsheet

servidor: 76.13.228.60 · srv1608561.hstgr.cloud · Hostinger KVM 4 · Ubuntu 24.04 LTS
app path: /opt/app/ · env em /opt/app/.env-prod · supervisor + caddy + nginx
flag default: MIGRATE_NEGOTIATION_TO_LANGGRAPH=false · rollback ~50s via sed + docker compose --force-recreate
endpoints: frontend app-v2.negociasimples.com.br · API api-v2.negociasimples.com.br/api · webhook /webhook
ci/cd: GitHub Actions · push launch/v2 → deploy automático · golden eval label-triggered
deploy fast-path: scp + docker cp + supervisorctl restart 'negocia:fastapi' (sem rebuild)

Próximas fases CREWAI_TO_LANGGRAPH Fases 2-5 migram AUTH, ONBOARDING+SALES+PLANS+CONTRACT, e CHECKOUT+INGESTION para o mesmo padrão de StateGraph. Cleanup final remove crewai>=0.22.5. Pattern (perceive → branches → finalize) já estabelecido na Fase 1 e validado contra os 6 smoke tests reais — pronto pra ser replicado.