Arquitetura

Estrutura de alto nível da plataforma Brandvelia e como as peças se conectam.

---

Stack

Camada	Tecnologia
App	Next.js, App Router, src/, Tailwind v4, shadcn/ui + Lucide
Linguagem	TypeScript, strict
Dados	Supabase (projeto panoptes, schema brandvelia), RLS + views
IA	OpenRouter via gateway interno server-only (packages/ai)
Integrações	packages/integrations — ClickBank (LinkBuilder/INS/QuickStats/Marketplace/Opportunity Score), Meta read-only
Tipos	packages/types — IDs nominais + schemas Zod + enums de domínio

---

Domínios (workspaces)

Cada afiliado autenticado possui um workspace isolado (bv_workspace_id): um conjunto de produtos (do ClickBank/LinkBuilder), métricas de tráfego, dados financeiros e modelos de IA. O isolamento é garantido por RLS nas tabelas base — e forced RLS nas tabelas do motor de decisão.

Fluxo de acesso a dados: tabela bv_* → view auto-atualizável public.bv_* (security_invoker = true) → API REST. O RLS das tabelas base aplica-se na view, então dados nunca vazam entre workspaces.

---

Fluxo de dados

Visitante               Workspace do operador            Supabase compartilhado
   │                       │                                 │
   │  POST /api/track      │        INSERT bv_visits          │
   │───────────────▶  ┌───▶│  (atribuição via click_id)       │
   │                   └───▶│        (RLS por workspace_id)    │
   │                       │                                 │
   │  /api/radar           │        CREATE / refresh          │
   │◀────┬────────────┬────│  produtos + opportunity score    │
   │     │ ClickBank   │   │        (aditivo, brandvelia only)│
   │     │ (API v2)    │   │                                 │
   │◀────┴─────────────┴───┤        linkbuilder → public.bv_offer

---

Fluxo do frontend

1. Vision Board — captura a ideia de produto; gera URL de afiliado LinkBuilder → cria uma BV_Offer (síncrona, persistida no Supabase).
2. Radar — consulta o ClickBank por produto; ranqueia com um Opportunity Score (economics, gravityFit, funnelQuality, trafficFit, creativePotential, complianceScore) para revelar o que vale construir.
3. Ofertas — um dashboard por produto; analytics e métricas de settlement.
4. Campanhas — roteamento de tráfego entre plataformas (Google, Meta, TikTok) com orçamentos e fases de decisão.
5. Criativos — criativo gerado por IA por plataforma, público e tom.
6. Landing Pages — destinos próprios orientados a métricas (preview + slug).
7. Leads — captura → CRM → finanças → settlement.
8. Finanças — P&L completo reconciliado contra o snapshot de marketplace (import CSV) e inputs de capital.
9. Motor de Decisão — evidência → capital → cenários → recomendação SHADOW → decisão humana → fase de campanha.

---

Pipeline de IA

[componente copilot]
  └─ [snapshot: workspace_id, transactions] → [invoca modelo: google/gemini-2.5-flash]
       └─ resposta textual (cita valores calculados em SQL) → [aiRuns.log]

• Chaves de modelo são server-only; a fronteira requisição→provedor é isolada por funcionalidade (AI_LINKER).
• Toda execução é logada (bv_ai_runs); o custo por chamada vem do registro bv_ai_models.
• Nenhum provedor/modelo é chamado diretamente do client.
• Claims factuais passam pelo validador de evidência do Motor de Decisão.

Entrypoint de agente

fetch(api, {
  headers: { "AI_Model": name, "AI_Tags": JSON.stringify(t), "Content-Type": "application/json" },
  method: "POST",
});

---

Agendamento & limites de função (Vercel)

Verificado contra a documentação da Vercel em 2026-08-20 (limites dependem do plano — revalidar após qualquer mudança de plano):

Preocupação	Hobby	Pro
Cron jobs por projeto	100	100
Frequência mínima de cron	1× por dia (expressões mais frequentes falham o deploy)	1× por minuto
Precisão do cron	por hora (±59 min)	por minuto
Duração máxima de função	300 s (padrão e máximo)	300 s padrão, até 800 s (1800 s beta)

Consequências para a Brandvelia:

• Expressões cron são sempre UTC. No Hobby o apps/web/vercel.json tem SÓ jobs diários (qualquer */N falha o deploy); a alta frequência roda no cron-job.org (console, grátis, até 60 exec/h — ver docs/INFRA.md): google-conversions a cada 10 min, google-campaigns a cada 5 min, syncs ClickBank 2x/dia. Fallback manual em .github/workflows/cron.yml (CRON_SECRET + SITE_URL).
• Rotas disparadas por cron carregam o user agent vercel-cron/1.0 e exigem bearer CRON_SECRET (defesa em profundidade).
• Trabalhos em batch (upserts de feed, deletes de retenção) devem caber nos 300 s: escritas em chunks (500 linhas/batch) e deletes curtos apoiados por índice.

---

Status

• V1 (Feature Manager): funcionando (Vision Board, Radar, dashboard).
• V2: aba EXPERIMENT, gráficos, relatórios custom e dashboard financeiro completo em desenvolvimento.
• Motor de Decisão (fases 0–4): implementado em SHADOW — evidência, capital, cenários, recomendações, decisões humanas, fases, alertas e score v2.