BragaCode - site institucional e portfólio

Site comercial da BragaCode, operação de desenvolvimento de software fundada por Pedro Braga. O projeto apresenta serviços, cases, trajetória e canais de contato com conteúdo em português brasileiro.

Planejamento atual

A revisão de 2026-09-29 acrescenta o Master Plan Braga Code 2026–2028, com auditoria dos três projetos, catálogo das 86 oportunidades e prompt mestre de execução. O plano propõe evolução integrada de BragaCode, ComércioBES e BragaCommerce, com responsabilidades e deploys independentes, sem declarar os módulos futuros disponíveis.

Consulte também o índice de documentação, o roadmap com issues reais, o posicionamento e a auditoria de publicação.

O GitHub executa CI a cada push na main; publicação automática no Sites não foi comprovada. Domínio, canais, autorização de cases e lançamento continuam nas issues existentes.

Stack

• Next.js com App Router e Server Components;
• React e TypeScript;
• Tailwind CSS v4 com design tokens em CSS;
• Zod para validação do formulário;
• Sentry para monitoramento opcional e sanitizado no Cloudflare Worker;
• fontes variáveis locais Manrope e JetBrains Mono;
• vinext/Vite para build compatível com Cloudflare Workers e Sites.

Requisitos

• Node.js 22.13 ou superior;
• npm 10 ou superior.

Configuração local

1. Instale dependências:

   npm ci

2. Copie .env.example para .env.local e preencha apenas as integrações que deseja testar.

3. Inicie o ambiente local:

   npm run dev

4. Abra a URL indicada no terminal.

Sem provedor de contato configurado, o formulário valida os dados e orienta a usar o WhatsApp. Nenhum analytics é carregado por padrão.

O monitoramento também é opcional. Quando SENTRY_DSN está ausente, nenhum evento é enviado.

Scripts

npm run dev      # desenvolvimento com HMR
npm run build    # build de produção
npm run lint     # ESLint
npm test         # build e smoke tests das rotas
npm run test:e2e # fluxos críticos em Chromium desktop/mobile, Firefox e WebKit
npm run test:lighthouse # orçamento sintético de performance, acessibilidade e SEO

Na primeira execução local dos testes de navegador, instale os navegadores com npx playwright install chromium firefox webkit. No Windows, o Playwright usa o servidor Vite porque o cache de arquivos estáticos do vinext start 0.0.50 ainda normaliza caminhos como POSIX; no CI Linux, os mesmos testes usam o bundle de produção.

Qualidade contínua

Pull requests e pushes em main executam automaticamente:

• instalação reproduzível com npm ci e Node.js 22;
• lint;
• build de produção;
• smoke tests de rotas, SEO e validação do formulário;
• testes de navegador dos fluxos críticos em desktop e mobile;
• auditoria das dependências usadas em produção.

O merge deve acontecer somente quando o workflow CI estiver aprovado.

Estrutura

app/              rotas, metadata, sitemap, robots e endpoint de contato
components/       layout, formulário, cases, SEO e elementos reutilizáveis
content/          dados tipados da empresa, serviços, projetos e FAQ
docs/             requisitos, arquitetura, sitemap, design, roadmap e lançamento
lib/              URLs, SEO e validação
public/           assets públicos, incluindo Open Graph
tests/            smoke tests de renderização server-side

Conteúdo dos projetos

Edite content/projects.ts. Cada projeto possui problema, contexto, solução, funcionalidades, tecnologias, resultados, métricas, galeria e metadata. O slug gera a rota em /projetos/[slug], o sitemap e os links relacionados.

Projetos em protótipo devem continuar com status Protótipo e texto explícito sobre maturidade. Métricas só devem ser publicadas quando houver fonte ou autorização.

Formulário

O POST /api/contact inclui:

• validação Zod;
• limite de payload;
• honeypot;
• tempo mínimo de preenchimento;
• rate limit de melhor esforço por instância;
• Cloudflare Turnstile opcional;
• envio por Resend ou webhook assinado, com idempotência e novas tentativas controladas.

Para Resend, configure RESEND_API_KEY, CONTACT_TO_EMAIL e CONTACT_FROM_EMAIL. Para webhook, configure CONTACT_WEBHOOK_URL e CONTACT_WEBHOOK_SECRET; ele tem prioridade. Todas as tentativas do mesmo contato usam Idempotency-Key: contact/<UUID>. O receptor do webhook deve persistir essa chave e ignorar duplicatas.

O webhook recebe X-BragaCode-Timestamp e X-BragaCode-Signature, calculada como HMAC SHA-256 de <timestamp>.<corpo>. Valide a assinatura com comparação em tempo constante e rejeite timestamps antigos antes de processar o lead. Campos do honeypot, Turnstile e controle de tempo não são enviados.

O rate limit em memória reduz abuso simples, mas não substitui proteção persistente ou regra de borda em produção.

Analytics

• Recomendado — Plausible: NEXT_PUBLIC_ANALYTICS_PROVIDER=plausible e NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL com a URL única fornecida em Site Settings > Site Installation.
• Alternativa mantida — Google Analytics: NEXT_PUBLIC_ANALYTICS_PROVIDER=ga e NEXT_PUBLIC_GA_ID.
• Sem as variáveis correspondentes, nenhum script ou listener de analytics é carregado.

Eventos implementados:

• WhatsApp Click: links para wa.me;
• Contact Form Submitted: somente após resposta de sucesso, com origem e tipo de projeto, sem nome, e-mail ou telefone;
• Case Click: navegação para uma página individual de projeto;
• Service Click: navegação para uma página individual de serviço.

No Plausible, crie metas com esses quatro nomes exatamente como escritos. O cadastro do domínio, a verificação da instalação, o Search Console e o envio do sitemap são etapas manuais.

SEO

• metadata e canonical individuais;
• Open Graph e Twitter Card;
• app/sitemap.ts e app/robots.ts;
• JSON-LD de Organization, ProfessionalService, Person, Service, CreativeWork e BreadcrumbList;
• conteúdo server-rendered e URLs estáveis.

Defina NEXT_PUBLIC_SITE_URL com o domínio HTTPS final antes do build público para gerar canonicals, sitemap e imagens sociais corretos.

Artigos em MDX

Os artigos ficam em content/articles/*.mdx. O frontmatter obrigatório contém slug, title, description, publishedAt, status, readingTime, category, serviceSlugs e projectSlugs.

Somente arquivos com status: publicado entram na listagem e no sitemap. content/articles.ts valida o frontmatter com Zod durante o build. Blocos de código recebem destaque server-side via Shiki/rehype-pretty-code, sem JavaScript de syntax highlighting no navegador.

Para publicar um artigo:

1. criar o .mdx com slug único e descrição entre 80 e 180 caracteres;
2. relacionar ao menos um serviço ou projeto pertinente;
3. revisar afirmações, exemplos e dados confidenciais;
4. alterar o status para publicado;
5. executar npm run lint e npm test.

Versão em inglês

As rotas /en, /en/services, /en/projects, /en/about, /en/contact e as páginas de AquaFlora, PromoGames, Braga Commerce e JoysticKnights em /en/projects/[slug] têm conteúdo próprio em inglês. O seletor PT/EN mantém pares equivalentes quando existem e volta à Home do outro idioma para conteúdo ainda não traduzido.

createMetadata gera canonical, hreflang para pt-BR, en e x-default, além do locale correto no Open Graph. O sitemap repete os pares de idioma com alternates. Um script mínimo no <head> ajusta document.documentElement.lang antes do conteúdo e cada página inglesa também declara lang="en" no container principal.

O formulário usa rótulos e mensagens em inglês, mas preserva os valores internos aceitos pelo endpoint. A mensagem de WhatsApp também é localizada. Artigos e páginas individuais de serviço ainda existem somente em português e devem apontar para a Home equivalente ao alternar o idioma.

Deploy

Sites/Cloudflare

O projeto mantém a configuração vinext e o plugin Sites. Gere o build com npm run build, configure as variáveis no ambiente de hospedagem e publique o artefato resultante pelo fluxo Sites.

Outro provedor Next.js

O conteúdo e os componentes seguem APIs do App Router. Como a base atual usa vinext para Workers, valide o adaptador do provedor e preserve as variáveis de ambiente. Não publique .env.local.

Documentação de produto

• Requisitos
• Arquitetura
• Sitemap
• Design system
• Dados de projetos
• Roadmap, milestones e backlog
• Decisões técnicas
• ADR — CMS e fluxo editorial
• Checklist de lançamento
• Operação e monitoramento
• Integração operacional de leads
• Auditoria de qualidade e lançamento

Materiais para etapas manuais

• Autorização de divulgação de case
• Inventário de screenshots e assets
• Solicitação e aprovação de depoimento

Pendências antes do lançamento público

• confirmar domínio e e-mail comercial;
• revisar WhatsApp público;
• configurar o provedor do formulário e Turnstile;
• obter autorização para marcas, screenshots e depoimentos;
• revisar os textos legais conforme a estrutura jurídica real;
• executar o checklist de acessibilidade, performance e compatibilidade em produção.