Ir para o conteúdo

Início Rápido (Getting Started)

Repositório e Ambientes

  • Repositório oficial: EuVinicios/mypaidtraffic (privado).
  • Hospedagem da aplicação: Projeto Vercel mypaidtraffic (brandvelia.com, app.brandvelia.com).
  • Banco de dados: Projeto Supabase panoptes (schema isolado brandvelia).
  • Documentação técnica: Site MkDocs hospedado em docs.brandvelia.com.

Stack Tecnológica

Camada Tecnologia
Monorepo & Build pnpm workspaces + Turborepo
Tipagem & Linguagem TypeScript em modo strict
Aplicação Web Next.js (App Router, diretório src/, Tailwind CSS v4)
Banco de Dados & Auth Supabase (PostgreSQL, Row-Level Security, Edge Functions)
Gateway de IA OpenRouter via provedor interno server-only com JSON Schema
Rede de Afiliados ClickBank (LinkBuilder, INS 8.0, QuickStats API, Scraper)
Design System / UI Radix UI + shadcn/ui + Lucide Icons

Requisitos do Sistema

  • Node.js: Versão 20 ou superior (Node 22 recomendado)
  • pnpm: Gerenciador de pacotes padrão do monorepo
  • Python 3: Usado exclusivamente para a documentação MkDocs no ambiente virtual isolado .venv-docs

Comandos Principais (Executar da raiz do Monorepo)

pnpm install      # Instala todas as dependências dos workspaces
pnpm build        # Build de produção (Turborepo → Next.js)
pnpm lint         # Validação de código com ESLint
pnpm typecheck    # Verificação estrita de tipos com tsc --noEmit
pnpm test         # Execução dos testes unitários com Vitest

Os três pacotes internos compartilhados são: - packages/types — Tipos TypeScript de domínio, IDs nominais (BV_ID) e esquemas Zod compartilhados. - packages/ai — Gateway interno de comunicação com a API do OpenRouter. - packages/integrations — Adaptadores de integração com o ClickBank (descriptografia INS, normalização de pedidos, link builder e opportunity score).

Estrutura do Monorepo

mypaidtraffic/
├── apps/web/                      # Aplicação Next.js (root directory da Vercel)
│   ├── src/app/                   #   Rotas do App Router (páginas e API route handlers)
│   └── src/components/            #   Componentes do shadcn/ui e layout admin
├── packages/
│   ├── types/                     #   @brandvelia/types (schemas Zod e tipos)
│   ├── ai/                        #   @brandvelia/ai (Gateway OpenRouter)
│   └── integrations/              #   @brandvelia/integrations (Adaptadores ClickBank)
├── supabase/migrations/           #   Migrations SQL versionadas (aplicar com `supabase db push`)
├── docs/                          #   Documentação oficial (Material for MkDocs)
└── mkdocs.yml                     #   Configuração do site de documentação

A árvore de rotas autenticadas sob apps/web/src/app/(admin)/app/ organiza-se pelos módulos da plataforma: - /app/dashboard — Visão geral da operação e métricas do dia. - /app/radar — Radar de oportunidades e diagnóstico de mercado com IA. - /app/offers — Catálogo de ofertas, comissões e gerador de HopLinks. - /app/campaigns — Campanhas de tráfego, orçamentos e fases de execução. - /app/creatives — Criação de anúncios e copys compliant com IA. - /app/landing-pages — Editor schema-driven de bridge e presell pages. - /app/copilot — Assistente de IA para perguntas de negócio baseadas em SQL. - /app/leads — CRM de contatos, eventos e conformidade LGPD/GDPR. - /app/experiments — Testes A/B e atribuição estatística. - /app/finance — Demonstrativo financeiro consolidado, conciliação e capital. - /app/integrations — Webhooks, chaves de API e status de sincronização. - /app/manual — Manual interativo do afiliado profissional embutido no app. - /app/settings — Configurações da conta e workspaces.

Configuração e Variáveis de Ambiente

As configurações sensíveis ficam restritas exclusivamente ao ambiente do servidor:

  • SUPABASE_SERVICE_ROLE_KEY / SUPABASE_URL — Acesso privilegiado ao banco para API routes e webhooks.
  • NEXT_PUBLIC_SUPABASE_ANON_KEY / SUPABASE_URL — Chave pública para autenticação de clientes e sessões.
  • OPENROUTER_API_KEY — Chave do gateway de IA (somente servidor).
  • CLICKBANK_NOTIFICATION_SECRET — Segredo de descriptografia do webhook INS 8.0.
  • CLICKBANK_API_KEY_1 — Chave única API Order Read do ClickBank (API Management); CLICKBANK_API_KEY_2 é opcional para uma 2ª conta. O par antigo dev:clerk retorna 401.
  • CRON_SECRET — Token de autorização para as rotas agendadas em /api/cron/*.

Portões de Qualidade (Gates de Conclusão)

Antes de qualquer merge ou conclusão de tarefa:

pnpm lint && pnpm typecheck && pnpm build && pnpm test

Todos os quatro comandos devem passar sem nenhum erro.