VEK1 — Arquitetura de Landing Pages

Decisão: Estrutura de LP com estratificação de métricas (PostHog + Swarm)

Cada landing page da VEK1 segue uma arquitetura consistente que garante eventos PostHog corretos por página/sessão e alimenta dados estruturados pro Swarm.

Estrutura de cada LP

app/
  [slug]/
    page.tsx           → Server Component de entrada (metadata + layout)
    actions.ts         → Server Actions específicas da LP
    components/
      Hero.tsx         → Componente Client (PostHog pageview + session start)
      Benefits.tsx
      CTA.tsx
      SocialProof.tsx
      Footer.tsx
    lib/
      metrics.ts       → Eventos PostHog tipados (page_view, scroll_depth, cta_click, form_submit)

Princípios de arquitetura

Server Component como raiz — page.tsx é Server Component puro (metadata, SEO, layout wrapper)
Client Components só onde tem interação — Hero (CTA click), Form (submit), carrosséis de depoimento
Eventos PostHog centralizados — lib/metrics.ts exporta funções tipadas, uma fonte da verdade
Estratificação de métricas — cada evento carrega page_slug, session_id, variant (A/B test), referrer — Swarm consome depois pra montar funil
Nova LP = nova page route + metrics.ts — não reutiliza genérica que perde contexto

Eventos PostHog por LP

Evento	Disparo	Payload
`lp_page_view`	mount do Hero	`{ slug, session_id, referrer, utm_source, utm_campaign, variant }`
`lp_scroll_25` / `50` / `75` / `100`	IntersectionObserver no viewport	`{ slug, session_id, depth }`
`lp_cta_click`	clique no CTA principal	`{ slug, session_id, cta_text, cta_location }`
`lp_form_submit`	submit de form (se houver)	`{ slug, session_id, form_type }`

Pipeline Swarm + PostHog

Swarm tem um agente de pipeline de LP dedicado que:
1. Cria a landing page (Next.js route + componentes + metrics.ts)
2. Registra os eventos PostHog esperados no kit_meta do produto
3. Não reintroduz bugs de issues anteriores (verifica checklist antes de abrir PR)
A métrica estratificada permite ao Swarm saber qual LP converte, qual variante ganha, e qual traffic source performa melhor
O agente da pipeline é autocontido: recebe briefing + referências de LPs anteriores aprovadas, e gera o código completo testado

Property-based testing vs testes unitários

Para o código de backend / agentes (vek1-api, agentes Swarm):

Specs formais + property-based tests em vez de testes unitários tradicionais
Spec documenta entradas/saídas esperadas, invariantes, e regras de validação
PBT garante cobertura de casos de borda que testes unitários manuais perdem
Ex: função de parse de lead → testar com qualquer string válida/inválida mantém invariantes

Para landing pages (Next.js frontend):

Testes unitários são menos necessários (componentes são majoritariamente UI pura)
Mas a pipeline de entrega autônoma precisa de QA melhor do que "agente relendo código"
Solução: o agente executor roda a LP, verifica PostHog events no console, valida Lighthouse, e um agente auditor revisa o output (não o código) contra o spec