Decisões Arquiteturais (ADRs)¶

Este documento contém todas as Architectural Decision Records do projeto SellSync.

Formato: Cada ADR segue template padronizado com Contexto → Decisão → Razões → Alternativas → Consequências → Revisão

ADR-001: Gemini 1.5 Pro/Flash como LLM do SAC IA¶

Data: 2025-12-15 Status: ✅ Aceito Impacto: Alto - Define toda a stack de IA

Contexto¶

Precisamos escolher um LLM para o módulo SAC IA Q2 2026. O agente precisa: - Responder perguntas de pré-venda com base no catálogo ML - Consultar base de conhecimento via RAG (PDFs, manuais) - Manter tom de voz configurável - Custo controlado (target: <R$ 0.10 por resposta) - Latência <2s para boa UX

Decisão¶

Usar Gemini 1.5 Pro para respostas complexas + Gemini 1.5 Flash para respostas simples

Razões¶

Custo: 50% menor que GPT-4 (R$ 0.001/1k tokens Pro vs R$ 0.002 GPT-4)
Context window: 1M tokens (vs 128k GPT-4) - permite RAG massivo
Latência: 200-400ms média (vs 800ms+ GPT-4)
Integração: Google AI SDK nativo do Vercel/Next.js
Qualidade: 85%+ accuracy em testes internos (suficiente para Q1)
Flash tier: R$ 0.0001/1k tokens para perguntas simples (10x mais barato)

Alternativas Consideradas¶

GPT-4/GPT-4o (OpenAI):
❌ Custo 2x maior
❌ Context window menor (128k vs 1M)
✅ Accuracy ligeiramente superior (~2-3%)
Descartado: Custo não justifica ganho marginal
Claude 3 Opus/Sonnet (Anthropic):
✅ Qualidade excelente
✅ Context window grande (200k)
❌ Sem integração nativa Supabase Q1
❌ Custo similar ao GPT-4
Descartado: Complexidade integração Q1
Llama 3 70B (self-hosted):
✅ Custo zero após setup
❌ Complexidade infra (GPU, Kubernetes)
❌ Latência maior (precisa tuning)
Descartado: Over-engineering para Q1, considerar Q3

Consequências¶

✅ Positivas: - Custo controlado: ~R$ 0.05 por resposta (target atingido) - RAG ilimitado: 1M tokens = 100+ PDFs no contexto - Hybrid strategy: Flash para 70% perguntas, Pro para 30% complexas - SDK maduro: @google/generative-ai bem documentado

❌ Trade-offs: - Vendor lock-in Google (mitigação: abstração LLM layer Q3) - Accuracy 2-3% abaixo GPT-4 (aceitável para MVP) - Rate limits free tier: 15 RPM (precisa upgrade pago produção)

Implementação Técnica¶

// Hybrid strategy
const model = question.complexity === 'simple'
  ? 'gemini-1.5-flash'    // R$ 0.0001/1k tokens
  : 'gemini-1.5-pro'      // R$ 0.001/1k tokens

const response = await genAI.generateContent({
  model,
  prompt: buildPrompt(question, ragContext),
  temperature: 0.3,  // Low temperature = less hallucination
  maxTokens: 1000
})

Revisão¶

Q3 2026: Reavaliar se: - GPT-4o custo cair 50%+ - Claude integração melhorar - Accuracy Gemini < 80% (abaixo aceitável)

ADR-002: PostgreSQL + Supabase como Database¶

Data: 2025-12-10 Status: ✅ Aceito Impacto: Alto - Define toda a infraestrutura de dados

Contexto¶

Precisamos escolher database principal para SellSync. Requisitos: - Suporta pgvector para RAG (embeddings semânticos) - Managed service (não queremos gerenciar infra Q1) - Compatible com Prisma ORM - Auth integrada (OAuth Google, ML) - Storage para PDFs/arquivos - Custo viável para MVP (free tier + scale gradual)

Decisão¶

PostgreSQL via Supabase (não AWS RDS, não MongoDB Atlas)

Razões¶

pgvector nativo: Busca semântica essencial para RAG do SAC IA
Supabase = all-in-one: Database + Auth + Storage + Realtime
Free tier generoso: 500MB storage, 2GB bandwidth (viável para 100+ sellers)
Prisma compatible: Suporte first-class
DX excelente: Dashboard UI, logs, migrations automáticas
Auth built-in: OAuth Google/ML sem setup extra

Alternativas Consideradas¶

MongoDB Atlas + Vector Search:
✅ Vector search nativo
❌ Prisma suporte limitado (precisa raw queries)
❌ Sem auth/storage integrado
Descartado: Complexidade integração
AWS RDS + S3 + Cognito:
✅ Escalabilidade infinita
❌ Setup complexo (3 serviços separados)
❌ Custo mais alto (sem free tier real)
Descartado: Over-engineering Q1
PlanetScale (MySQL):
✅ Managed MySQL excelente
❌ Sem suporte pgvector (sem RAG)
Descartado: RAG é crítico

Consequências¶

✅ Positivas: - Stack unificado: 1 serviço = DB + Auth + Storage - pgvector 768d embeddings para RAG - Migrations via Prisma (DX incrível) - Free tier suficiente para beta (50-100 sellers)

❌ Trade-offs: - Vendor lock-in Supabase (mitigação: é PostgreSQL padrão, portable) - Free tier limits (500MB) - upgrade necessário >100 sellers - Realtime features não usadas Q1 (paga por recurso não usado)

Revisão¶

Q3 2026: Avaliar se precisa migrar para AWS RDS (se Supabase custo > R$ 2.000/mês)

ADR-003: Next.js 15 + React Server Components¶

Data: 2025-12-10 Status: ✅ Aceito Impacto: Alto - Define frontend/backend stack

Contexto¶

Escolher framework web para SellSync. Requisitos: - SSR para SEO landing pages - Server Actions para forms (sem API routes verbose) - Type-safe (TypeScript) - Deploy fácil (Vercel ideal) - DX moderna

Decisão¶

Next.js 15 App Router + React Server Components

Razões¶

Server Components: Fetch data no servidor (performance)
Server Actions: Forms sem API boilerplate
Type-safe: TypeScript + Prisma types end-to-end
Vercel deploy: Git push = deploy automático
Ecossistema: Maior do mercado React

Alternativas Consideradas¶

Remix: ✅ Excelente, ❌ Ecossistema menor - Descartado
SvelteKit: ✅ Performance, ❌ Time não conhece Svelte - Descartado
Next.js Pages Router: ❌ Legado, usar App Router - Descartado

Consequências¶

✅ DX excelente, deploy fácil, type-safety ❌ Bundle size maior que Svelte (aceitável)

Revisão¶

Estável - sem revisão planejada

ADR-004: Prisma como ORM¶

Data: 2025-12-10 Status: ✅ Aceito Impacto: Médio - Define data access layer

Decisão¶

Prisma ORM (não TypeORM, não Drizzle)

Razões¶

Prisma Client: Type-safe queries automáticas
Migrations: prisma migrate declarativo
Prisma Studio: UI para debug database
DX: Melhor do mercado TypeScript ORM

Alternativas Consideradas¶

TypeORM: ❌ Decorators verbosos, menos type-safe - Descartado
Drizzle: ✅ Mais leve, ❌ Menos maduro, docs piores - Descartado
Raw SQL: ❌ Sem type-safety - Descartado

Consequências¶

✅ Type-safety completo, migrations fáceis ❌ Queries complexas precisam raw SQL às vezes

Revisão¶

Estável

ADR-005: BullMQ para Jobs Assíncronos¶

Data: 2025-12-12 Status: ✅ Aceito Impacto: Médio - Define queue system

Contexto¶

Precisamos processar jobs assíncronos: - Fetch perguntas ML API (a cada 5min) - Gerar respostas IA (background) - Enviar emails (não bloquear requests) - Retreinamento semanal (feedback loop)

Decisão¶

BullMQ + Redis (Upstash ou Railway)

Razões¶

Maduro: Usado por Vercel, Shopify, etc
Features: Retry, priority, scheduling, cron
Dashboard: Bull Board para debug
TypeScript: Suporte first-class

Alternativas Consideradas¶

Vercel Cron: ❌ Limitado a 1 job/min, sem retry - Insuficiente
Inngest: ✅ Excelente, ❌ Vendor lock-in - Considerar Q3
AWS SQS: ❌ Complexo para Q1 - Overkill

Consequências¶

✅ Sistema robusto, retry automático ❌ Precisa Redis managed (Upstash R$ 50/mês)

Revisão¶

Q3 - Avaliar Inngest se precisar mais features

ADR-006: Stripe para Pagamentos¶

Data: 2025-12-12 Status: ✅ Aceito Impacto: Médio - Define billing stack

Decisão¶

Stripe Subscriptions + Customer Portal

Razões¶

Subscriptions: Suporte nativo R$ 297/mês recorrente
Customer Portal: Self-service para sellers (trocar cartão, cancelar)
Webhooks: Robustos (invoice.payment_succeeded, etc)
Global: Aceita cartões Brasil + internacional
SDK: Melhor do mercado

Alternativas Consideradas¶

Pagar.me: ❌ SDK ruim, docs ruins - Descartado
Mercado Pago: ❌ Sem subscriptions robustas - Descartado
Paddle: ✅ Bom, ❌ Foco B2C não B2B - Descartado

Consequências¶

✅ Billing profissional, self-service sellers ❌ Taxa 3.9% + R$ 0.39 (custo aceitável)

Revisão¶

Estável

ADR-007: NextAuth.js para Autenticação¶

Data: 2025-12-12 Status: ✅ Aceito Impacto: Médio - Define auth stack

Decisão¶

NextAuth.js v5 (Auth.js)

Razões¶

OAuth: Google + ML OAuth built-in
Next.js: Integração nativa App Router
Session: JWT ou database sessions
Callbacks: Customize auth flow

Alternativas Consideradas¶

Supabase Auth: ✅ Bom, ❌ ML OAuth complexo - Descartado
Clerk: ✅ UI bonita, ❌ Custo alto - Descartado
Auth0: ❌ Overkill para Q1 - Descartado

Consequências¶

✅ OAuth fácil, DX excelente ❌ Precisa setup callback URLs (aceitável)

Revisão¶

Estável

ADR-008: RAG + pgvector para Base de Conhecimento (NÃO Templates)¶

Data: 2025-12-17 Status: ✅ Aceito Impacto: 🔥 CRÍTICO - Define arquitetura SAC IA

Contexto¶

PROBLEMA IDENTIFICADO: Wireframes 30 originais tinham "Templates de Resposta" com lógica IF/ELSE:

SE produto sem estoque → "Produto esgotado, aguarde reposição"
SE pergunta sobre garantia → "Garantia de 12 meses"

Feedback do usuário: "você ainda está insistindo em usar logica burra"

Isso é arquitetura ultrapassada que: - ❌ Não escala (precisa criar template para cada cenário) - ❌ Sem contexto (não usa dados do produto) - ❌ Inflexível (não adapta ao tom de voz) - ❌ Não compete com GoBots/Predize (usam IA real)

Decisão¶

RAG (Retrieval-Augmented Generation) + pgvector para busca semântica

Arquitetura: 1. Seller faz upload de PDFs/manuais 2. Sistema gera embeddings (768d vectors) via Gemini 3. Armazena em PostgreSQL com pgvector extension 4. Quando pergunta chega → busca top 5 chunks relevantes 5. Gemini gera resposta contextual baseada nos chunks + catálogo ML

Razões¶

Contextual: Usa informações REAIS do seller (não templates genéricos)
Escala: Funciona para qualquer produto/pergunta
Flexível: Adapta tom de voz, instruções customizadas
Competitivo: GoBots e Predize usam RAG (não templates)
Accuracy: +40% vs templates IF/ELSE

Alternativas Consideradas¶

Templates IF/ELSE:
❌ Lógica burra, não escala
❌ Não compete com mercado
REJEITADO (ver REJ-001)
LLM sem RAG (só catálogo ML):
❌ Sem conhecimento específico do seller
❌ Hallucinations (inventa informações)
Insuficiente
Fine-tuning modelo custom:
✅ Accuracy máxima
❌ Custo R$ 5.000+ por seller
❌ Complexidade altíssima Q1
Overkill (considerar Q4)

Consequências¶

✅ Positivas: - Respostas contextuais baseadas em docs reais - Seller ensina a IA (upload PDFs) - Compete com GoBots/Predize - Escalável (funciona para 1 ou 10.000 sellers)

❌ Trade-offs: - Complexidade maior que templates - Precisa pgvector (depende PostgreSQL) - Embeddings custam ~R$ 0.01 por PDF (aceitável)

Implementação Técnica¶

// 1. Upload PDF → Embeddings
async function uploadKnowledgeBase(sellerId: string, pdf: File) {
  const text = await extractTextFromPDF(pdf)
  const chunks = splitIntoChunks(text, 500) // 500 chars each

  const embeddings = await genAI.embedContent(chunks)

  await prisma.$executeRaw`
    INSERT INTO knowledge_base (seller_id, chunk, embedding)
    VALUES ${chunks.map((chunk, i) =>
      `(${sellerId}, ${chunk}, ${embeddings[i]})`
    )}
  `
}

// 2. Query RAG
async function getRelevantContext(sellerId: string, question: string) {
  const questionEmbedding = await genAI.embedContent(question)

  const results = await prisma.$queryRaw`
    SELECT chunk, embedding <=> ${questionEmbedding} AS distance
    FROM knowledge_base
    WHERE seller_id = ${sellerId}
    ORDER BY distance ASC
    LIMIT 5
  `

  return results.map(r => r.chunk)
}

// 3. Generate answer
const context = await getRelevantContext(sellerId, question.text)
const answer = await genAI.generateContent({
  prompt: `
    Contexto da base de conhecimento:
    ${context.join('\n---\n')}

    Produto: ${product.title}
    Pergunta: ${question.text}

    Responda baseado APENAS nas informações acima.
  `
})

Revisão¶

Q3 2026: Avaliar fine-tuning se accuracy < 85%

ADR-009: Agentes Especializados por Categoria (5 tipos)¶

Data: 2025-12-17 Status: ✅ Aceito Impacto: Alto - Define accuracy IA

Contexto¶

Análise competitiva mostrou que GoBots tem 50+ bots especializados por segmento e atinge +15-20% accuracy vs agente genérico.

SellSync originalmente tinha 1 agente genérico para todos os produtos.

Decisão¶

5 agentes especializados por categoria de produto

Eletrônicos: Specs técnicas, garantia, compatibilidade, certificações
Moda: Tamanhos, tecidos, cores, medidas, tabelas de tamanho
Casa & Decoração: Dimensões, materiais, instalação
Automotivo: Compatibilidade veículo (ano/modelo), instalação
Genérico: Fallback para outras categorias

Razões¶

Accuracy: +20% vs agente genérico (benchmark GoBots)
Vocabulário especializado: "Voltagem" relevante para eletrônicos, não moda
Competitivo: GoBots faz isso, Predize tem 6 agentes
Experiência seller: Respostas mais precisas = menos edições

Alternativas Consideradas¶

1 agente genérico:
❌ Accuracy 20% menor
Descartado
20+ agentes (granular como GoBots):
✅ Accuracy máxima
❌ Complexidade alta Q1
Adiar para Q3

Consequências¶

✅ Accuracy +20%, respostas especializadas ❌ Precisa detectar categoria (via ML API)

Implementação¶

const agentPrompts = {
  electronics: "Você é especialista em eletrônicos. Foque em specs técnicas...",
  fashion: "Você é especialista em moda. Foque em tamanhos, tecidos...",
  home: "Você é especialista em casa. Foque em dimensões, materiais...",
  automotive: "Você é especialista em automotivo. Foque em compatibilidade...",
  generic: "Você é assistente generalista..."
}

const category = detectCategory(product.mlCategory) // ML API category
const prompt = agentPrompts[category]

Revisão¶

Q3 2026: Expandir para 10-15 categorias se accuracy melhorar

ADR-010: Mercado Livre Único Marketplace Q1-Q2¶

Data: 2025-12-15 Status: ✅ Aceito Impacto: Alto - Define escopo MVP

Contexto¶

Predize tem 11 marketplaces integrados. Discussão se SellSync deve ter multi-marketplace desde Q1.

Decisão¶

Apenas Mercado Livre Q1-Q2, expansão Q4

Razões¶

Complexidade: Cada marketplace tem API diferente (semanas de integração)
Validação: ML é maior marketplace Brasil (70% market share)
Foco: Melhor ter ML perfeito que 3 marketplaces medíocres
Feedback usuário: "não vejo necessidade em abordar outras plataformas"

Alternativas Consideradas¶

Multi-marketplace Q1:
✅ Feature parity com Predize
❌ Atraso MVP 2-3 meses
Descartado

Consequências¶

✅ MVP mais rápido, foco em qualidade ML ❌ Sem feature parity Predize Q1 (aceitável)

Roadmap Multi-marketplace¶

Q4 2026: Shopee, Amazon, B2W (mercados secundários Brasil)

Revisão¶

Q3 2026: Avaliar demanda sellers por Shopee/Amazon

ADR-011: Git Hook Local para Indexação RAG (não GitHub Actions)¶

Data: 2026-01-01 Status: ✅ Aceito Impacto: Médio - Define automação de indexação de documentos

Contexto¶

Precisamos automatizar a indexação de documentos DOCS/ no Supabase (pgvector) para manter o RAG atualizado. Requisitos: - Auto-indexar quando docs são alterados - Custo zero de infraestrutura - Funcionar de forma transparente no workflow do desenvolvedor

Decisão¶

Usar git hook local (pre-push) em vez de GitHub Actions para indexação RAG

Razões¶

Conectividade: GitHub Actions não suporta IPv6 nativamente, e o Supabase só tem registro DNS AAAA (IPv6)
Custo: Zero custo vs. ~R$ 100-200/mês (self-hosted runner para resolver IPv6)
Velocidade: Indexação local é mais rápida (sem cold start de CI)
Simplicidade: Menos moving parts (sem secrets management em CI)

Alternativas Consideradas¶

GitHub Actions com Pooler (porta 6543):
❌ Ainda falha - Pooler também só tem IPv6
Descartado: Problema de infraestrutura do Supabase
GitHub Actions + Self-Hosted Runner:
✅ Controle total de network
❌ Custo: ~$50/mês por runner
❌ Complexidade: Manter VM/container
Descartado: Over-engineering para fase atual
GitHub Actions + Supabase Edge Function como Proxy:
✅ Funcionaria tecnicamente
❌ Complexidade adicional
❌ Latência: request → edge → database → edge → response
Descartado: Gambiarra desnecessária

Consequências¶

✅ Positivas: - Custo zero de CI/CD para indexação - Funcionamento garantido localmente - Setup versionado em scripts/git-hooks/ - Auto-setup via npm run setup:hooks ou npm run prepare - Health check disponível via MCP validateDocsSync

❌ Trade-offs: - Single Point of Failure: Só funciona na máquina do desenvolvedor - Onboarding: Novos devs precisam rodar npm run setup:hooks - Colaboração: Se outros devs fizerem push sem o hook, docs não serão indexados

Mitigações Implementadas¶

Risco	Mitigação
Single Point of Failure	Health check `validateDocsSync` detecta drift
Onboarding manual	`npm run prepare` auto-configura (Husky pattern)
Docs desincronizados	Alertas via MCP quando detecta arquivos não indexados
Script não versionado	Movido para `scripts/git-hooks/` (versionado)

Implementação Técnica¶

# Setup automático (qualquer dev)
npm run setup:hooks

# Hook detecta arquivos alterados e indexa
git push  # → pre-push hook → detecta DOCS/*.md → indexa pillar → push

# Health check (via MCP)
validateDocsSync({ pillar: 'engineering' })

Arquivos Criados¶

scripts/git-hooks/pre-push - Hook versionado
scripts/setup-hooks.sh - Script de setup
package.json - Comandos npm (setup:hooks, docs:index)

Revisão¶

Q2 2026: Reavaliar quando: - Time crescer para 3+ devs (considerar self-hosted runner) - Supabase adicionar registro A (IPv4) ao DNS - Vercel/Railway oferecer integração nativa com Supabase

ADR-012: Query Expansion Estático para RAG (não LLM-based)¶

Data: 2026-01-01 Status: ✅ Aceito Impacto: Médio - Melhora recall do RAG sem custo adicional

Contexto¶

O RAG do SellSync usa busca híbrida (embedding + full-text). Porém, quando usuário pergunta "voltagem?" e o documento contém "tensão 220v", a busca full-text não encontra match. Query Expansion resolve isso expandindo a query com sinônimos antes da busca.

Duas abordagens foram consideradas: 1. Dicionário estático - Lista manual de sinônimos por categoria e-commerce 2. LLM-based - Gemini expande a query automaticamente

Decisão¶

Usar dicionário estático de sinônimos, com evolução para híbrido em fases

Razões (Baseado em consulta ao time de agentes - Score 8.3/10)¶

Custo zero: Não adiciona chamadas de API (vs. +1 Gemini call/query)
Latência zero: Expansão in-memory instantânea (vs. +200ms API)
Robustez: Sem dependência de API externa para feature crítica
Escalabilidade: Funciona identicamente para 1k ou 100k sellers
Cobertura: ~95% das expansões e-commerce são previsíveis (vocabulário finito)

Votos dos Agentes¶

Agente	Voto	Confiança
AI Scientist	Opção 1 (Estático)	8/10
CFO	Opção 1 (Estático)	9/10
CPO	Opção 2 (LLM)	7/10
Pre-Mortem	Opção 1 (Estático)	8/10

Resultado: 3×1 para Dicionário Estático

Alternativas Consideradas¶

LLM-based (Gemini expande queries):
✅ Cobre edge cases complexos (peças automotivas específicas)
❌ +1 API call por query = custo escala
❌ +200ms latência impacta UX mobile
❌ Rate limit em pico (Black Friday) = SAC para
Descartado para MVP (considerar Fase 3)
Nenhuma expansão:
❌ Recall baixo para sinônimos comuns
❌ Usuário digita "voltagem", doc tem "tensão" = não encontra
Descartado: Problema real de UX

Consequências¶

✅ Positivas: - Melhora recall sem custo - Não degrada COGS de R$ 1,55/seller - Expansão instantânea (<1ms) - Dicionário extensível (Fase 2: enriquecimento automático)

❌ Trade-offs: - Manutenção manual do dicionário - Não cobre 100% dos edge cases (ex: compatibilidade complexa de peças) - Mitigado: Fase 3 adiciona LLM fallback para <5% queries sem match

Implementação Técnica¶

// Dicionário de sinônimos (mcp-server-sellsync/src/query-expansion.ts)
const SYNONYM_DICTIONARY = {
  'voltagem': ['voltagem', 'tensão', '110v', '220v', 'bivolt'],
  'tamanho': ['tamanho', 'tam', 'size', 'medida', 'número'],
  'serve': ['serve', 'compatível', 'funciona', 'encaixa', 'cabe'],
  // ~60 termos cobrindo 9 categorias e-commerce
};

// Expansão integrada no searchDocs
async function searchDocs(query) {
  const expandedQuery = expandQueryForFullText(query);
  // "voltagem?" → "voltagem | tensão | 110v | 220v | bivolt"
  return hybridSearch(expandedQuery, embedding);
}

Roadmap de Evolução¶

Fase	Timeline	Escopo
Fase 1 (MVP)	Semana 1-2	Dicionário estático (~60 termos, 9 categorias)
Fase 2	Mês 2	Pipeline enriquecimento (análise queries sem match)
Fase 3	Mês 3+	LLM fallback para <5% queries complexas

Arquivos Criados¶

mcp-server-sellsync/src/query-expansion.ts - Módulo de expansão
Integração em searchDocs() no index.ts

Métricas de Sucesso¶

Recall: +15-20% em queries com sinônimos comuns
Latência: <1ms adicional (vs. +200ms LLM)
Cobertura: 95% das queries e-commerce Brasil

Revisão¶

Q2 2026: Avaliar necessidade de Fase 3 (LLM fallback) baseado em: - % de queries com zero resultados após expansão - Tipos de queries não cobertas pelo dicionário

ADR-013: RAG Enhancements (Model Matrix + Progressive Disclosure + Triggers)¶

Data: 2026-01-02 Status: ✅ Aceito Impacto: Alto - Reduz custo LLM em 77%, melhora precisão em 50%

Contexto¶

Após análise do repositório wshobson/agents (99 agentes, 107 skills), identificamos 4 padrões de otimização aplicáveis ao SellSync:

Model Assignment Matrix: Usar modelos diferentes por criticidade (Opus/Sonnet/Haiku)
YAML Frontmatter Triggers: Metadata em DOCS para boost de relevância
Progressive Disclosure: 3 tiers de conteúdo para economizar tokens
Telemetria: Monitorar economia real vs teórica

Problema: Custo LLM crescente com escala. Estimativa: $900/mês com tudo Opus.

Decisão¶

Implementar os 4 padrões de otimização do wshobson/agents adaptados para SellSync

Razões¶

Economia comprovada: Benchmark validou -77% custo, -99% tokens
Zero dependências: Padrões de design, não bibliotecas externas
Baixo risco: Não altera lógica de negócio, apenas otimiza infra
Rápida implementação: 4h de trabalho total
Reversível: Se não funcionar, basta usar Sonnet para tudo

Alternativas Consideradas¶

Continuar com Sonnet para tudo:
✅ Simples, sem código novo
❌ Custo 3x maior que otimizado
Descartado: Economia justifica complexidade
Usar apenas Haiku:
✅ Custo mínimo
❌ Qualidade inferior para decisões críticas
Descartado: Risco de respostas ruins em SAC
Cache de respostas (Redis):
✅ Economia em queries repetidas
❌ Não resolve queries únicas (maioria)
Descartado: Complementar, não substituto

Consequências¶

✅ Positivas: - Economia de ~$560/mês em custos LLM - Latência -56% (Haiku: 407ms vs Opus: 2584ms) - Precisão RAG +50% com trigger matching - Tokens -99% com Progressive Disclosure (Tier 1) - Telemetria permite validação contínua

❌ Trade-offs: - Complexidade de código aumenta (4 novos módulos) - Requer manutenção de YAML frontmatter nos DOCS - Haiku pode gerar respostas de menor qualidade - Mitigado: SAC usa Sonnet (não Haiku)

Implementação Técnica¶

Arquivos Criados¶

mcp-server-sellsync/src/
├── model-matrix.ts          # Matriz de modelos por agente/operação
├── frontmatter-parser.ts    # Parser YAML para triggers
├── progressive-disclosure.ts # Sistema de 3 tiers
├── telemetry.ts             # Monitoramento de uso
├── rag-enhancements.ts      # Integração unificada
└── benchmark-enhancements.ts # Validação de métricas

Model Assignment Matrix¶

// Distribuição por criticidade
OPUS (10 agentes):    CEO, Pre-Mortem, CFO, Legal, AI Scientist...
SONNET (15 agentes):  CMO, CRO, Growth Hacker, CXO...
HAIKU (3 agentes):    Focus Guardian, People Ops, Community Builder

// Operações
OPUS (5):    strategic-decision, risk-assessment, legal-review...
SONNET (5):  generate-response, summarize-text, translate...
HAIKU (13):  classify-*, extract-*, validate-*, detect-*...

YAML Frontmatter¶

# Adicionado em DOCS críticos (unit-economics, master-document, etc.)
---
name: unit-economics
pillar: finance
priority: critical
triggers: [CAC, LTV, ARPU, churn, payback, margem bruta]
model: opus
summary: "Metodologia de unit economics. Valores no APEX SSoT."
---

Progressive Disclosure¶

Tier 1 (~50 tokens):   name + summary + triggers → SEMPRE retornado
Tier 2 (~300 tokens):  conteúdo principal → Se score > 0.75
Tier 3 (~1000 tokens): documento completo → Se score > 0.90

Telemetria¶

// Registra cada chamada
recordModelCall('sonnet', 'generate-response', 1500, 1200, true);

// Gera relatório semanal
const report = generateReport(7);
// Economia: 76.8% | Chamadas: Opus 11%, Sonnet 61%, Haiku 28%

Benchmark Validado¶

Métrica	Estimativa	Real	Status
Economia Tokens	-69%	-98.9%	✅ Superou
Economia Custo	-70%	-76.8%	✅ Superou
Ganho Precisão	+30%	+50%	✅ Superou

Monitoramento¶

Semanal: Revisar relatório de telemetria
Mensal: Comparar custo real vs projetado
Trimestral: Avaliar qualidade de respostas por modelo

Revisão¶

Q2 2026: Avaliar se: - Haiku está gerando respostas de qualidade aceitável - Economia real está alinhada com benchmark - Triggers estão melhorando precisão em queries reais

Referências¶

Repositório inspiração: wshobson/agents (MIT License)
Benchmark: mcp-server-sellsync/src/benchmark-enhancements.ts
Telemetria: mcp-server-sellsync/telemetry/model-usage.json

Template para Novos ADRs¶

## ADR-XXX: [Título da Decisão]

**Data:** YYYY-MM-DD
**Status:** Proposto | Aceito | Rejeitado | Substituído
**Impacto:** Alto | Médio | Baixo

### Contexto
[Por que estamos tomando esta decisão? Qual o problema?]

### Decisão
[O que decidimos fazer?]

### Razões
1. Razão 1
2. Razão 2

### Alternativas Consideradas
- **Alternativa A:**
  - ✅ Pró 1
  - ❌ Contra 1
  - **Descartado porque...**

### Consequências
**✅ Positivas:**
- Benefício 1

**❌ Trade-offs:**
- Trade-off 1

### Implementação Técnica
```code```

### Revisão
[Quando reavaliar? Q2? Q3?]

Última atualização: 2026-01-02 Total ADRs ativos: 13