Decisões técnicas

Postgres+pgvector self-hosted (não Supabase / não Neon)

• Stack VPS já lotada (lunacrm, mimic, vault, etc.); 1 container vs ~8 do Supabase self-host
• pgvector 0.8.2 cobre busca semântica sem dependência cloud
• Backup pendente (gap conhecido)

bge-m3 1024 dim (não OpenAI text-embedding-3-small 1536)

• Multilingual com força em PT-BR (modelo certificado pra PT/EN/ES)
• 1024 dim reduz storage/index size sem perda relevante de qualidade pra catálogos PME
• Self-hosted via Ollama — zero custo recorrente

DeepSeek (não OpenAI / Anthropic / outros)

• Custo bem menor (~10x mais barato que GPT-4o-mini com qualidade similar pra PT-BR)
• API OpenAI-compatible — zero refactor além de base_url
• Function calling completo (compatível com tool calling protocol da OpenAI)
• Trade-off: latência ~1.9s sem tools (vs 0.8s GPT-4o-mini), mas aceitável pra WhatsApp

psycopg2 síncrono (não asyncpg / não SQLAlchemy)

• Handlers FastAPI já síncronos — refactor pra async daria churn enorme sem ROI claro
• ThreadedConnectionPool cobre concorrência de tier-1 da PME (50-100 req/s)
• Trade-off: blocking I/O por request — não vai escalar pra 1000s req/s sem rework. Aceitável pro tamanho atual.

Per-domain routers com try/except ImportError no main.py

• Routers carregados lazy; falha de import logada como warning, não trava startup
• Permite deploy parcial (ex: novo router buggy não derruba auth/orders existentes)
• Trade-off: bugs de import passam silenciosos pro user (vê 404 em vez de stack). Mitigado por logs.

Token scope segregation (3 tokens isolados)

• INTERNAL_API_TOKEN (app) — domínios normais
• INTERNAL_AUTH_TOKEN — só /internal/auth/* (Better Auth)
• INTERNAL_WEBHOOK_TOKEN — webhooks (email, AbacatePay relay)
• Comprometimento de um escopo não dá acesso aos outros
• Fallback: app token serve pros 3 se dedicados ausentes (deploy parcial)
• Constant-time compare via hmac.compare_digest

Pydantic strict (extra="forbid") em todos endpoints

• 422 explícito se cliente manda campo desconhecido (anti-typo)
• Anti version-drift entre vek1 e vek1-api: schema mismatch falha rápido
• Trade-off: precisa coordenar updates de shape — vek1 e vek1-api precisam deploy junto se body schema mudar. Mitigação: deploys quase sempre simultâneos (single owner).

Cache em memória pro auth (não Redis)

• Singleton dict no processo, TTL curto (findUserByEmail, findSessionByToken)
• Reduz round-trip Postgres em hot path login
• Single instance container — cache fica consistente
• Trade-off: se escalar horizontal, cache fica inconsistente. Hoje single replica, ok. Próximo gap.

consumeOne(verification) atomic via DELETE..RETURNING

• Elimina race PKCE (find + delete tem janela)
• Single round-trip Postgres
• Implementado em auth_service.consume_verification(identifier, value) — Better Auth chama via adapter

Audit log via BackgroundTasks (não inline)

• audit_service.log_audit(...) chamado com bg.add_task(...) — não bloqueia request
• Trade-off: se request falhar antes do bg rodar, audit não grava. Aceitável (audit é nice-to-have, não SLA).

Function calling com 5 iterações máx

• LLM pode chamar várias tools em sequência (ex: search → get_details → create_order)
• Limite 5 evita loop infinito de hallucinação
• Trade-off: ocasionalmente trunca um fluxo complexo. Logs ajudam diagnosticar.

Skip backend persistence se lead_id present

• vek1 já grava em messages_history (e fileira extract-lead)
• Vek1-api gravava também → dupla escrita
• dd2ac9f removeu — vek1-api só grava se NÃO veio do vek1 (ex: chamada direta de teste sem lead_id)

dry_run no /chat

• dry_run: true simula side-effect tools (create_order, confirm_shipping) sem chamar HTTP
• Usado em tests/test_function_calling.py pra rodar prompts contra DeepSeek real sem poluir DB
• Sem dry_run, tests precisariam mock DeepSeek (frágil)

slowapi rate limit opcional

• try: import slowapi — não trava dev sem pip install slowapi
• Em prod, configurado em hot paths (chat, embed) com @limiter.limit("60/minute")
• Trade-off: rate limit in-memory por IP — não distribuído. Single replica ok.

GZip middleware ≥1KB

• Comprime responses ≥1KB
• Reduz egress Vercel/VPS em endpoints com listas grandes (orders/leads/messages_history)
• Melhora TTFB perceptível em dashboards

Logging verboso (com emojis)

• 📥 request, 📤 response, ✅ success, ❌ erro, 🚨 exceção crítica
• Stack trace completo em exceções não tratadas
• Trade-off: logs gordos — LOG_LEVEL=INFO em dev, considerar WARNING em prod se egress de logs ficar caro

init/01-init.sql versionado no repo

• pgvector ext + HNSW indexes + RPC match_documents_test
• Aplicado no init do container Postgres (/docker-entrypoint-initdb.d)
• Reproduzibilidade do schema parcial (Drizzle schema é o outro pedaço — vide vek1/data-model)

Sem ORM (raw SQL via psycopg2)

• Toda query escrita manual em services/*_service.py
• Vantagem: controle total (pgvector queries complexas, JOIN com filtro custom), zero overhead ORM
• Trade-off: typing manual via TypedDict / dict; refactor de schema dá churn (achar todas as queries que tocam coluna X)

Tests pytest com integration suite real

• tests/test_function_calling.py — chama DeepSeek real (não mock) + Postgres test DB
• Valida prompt behavior (anti-skip create_order)
• Trade-off: tests lentos (~30s suite full) + custo DeepSeek minimal mas real. Aceitável.

Single image Dockerfile (python:3.10-slim)

• Imagem ~250MB final
• Sem multi-stage build (não vale a pena pro tamanho)
• Restart unless-stopped (compose) — reinicia automático em crash