arquitetura-de-site-interativo

Arquitetura de Site Interativo

Resultado

Criar um site Next.js voltado para o público, de produção, cujo conteúdo, narrativa, identidade visual e qualidade de interação importam. Esta é uma arquitetura universal para sites centrados em conteúdo: sites de marca e marketing, sites de SaaS e produto, páginas de lançamento, propriedades editoriais, portfólios, comunidades, conferências, sites com formato de documentação e vitrines imersivas.

O núcleo é fixo:

• conteúdo renderizado no servidor;
• ilhas de cliente estreitas;
• contratos de conteúdo validados;
• tokens de design e movimento compartilhados;
• comportamento nativo do navegador;
• SEO e acessibilidade na resposta do servidor;
• orçamentos de desempenho por rota.

Selecione os módulos que o produto precisa:

Módulo	Use quando
Coleção e detalhe de conteúdo	O site possui projetos, artigos, produtos, pessoas, eventos ou registros similares
Portfólio ou estudos de caso	A organização precisa de prova por meio do trabalho
Arquivo imersivo	A exploração visual é uma superfície primária do produto
Loja	O site vende produtos digitais ou físicos
Adaptador de CMS	Editores publicam independentemente de versões
Formulário de contato	Um link de e-mail ou calendário é insuficiente

Não force módulos opcionais em um site que não precisa deles.

Perfis típicos reutilizam o mesmo núcleo:

• SaaS ou produto: landing, oferta, funcionalidades, coleção de conteúdo, docs ou changelog.
• Marca ou lançamento: narrativa de campanha, revelação do produto, lista de espera, prova social.
• Editorial: índice de coleção, detalhe do artigo, autores, tópicos, pesquisa.
• Comunidade ou conferência: palestrantes, programação, sessões, local, ingressos.
• Portfólio: índice de projetos, detalhe de caso, arquivo visual, contato.
• Comércio: catálogo, detalhe do produto, checkout, download ou entrega.

Leia antes de agir

• Leia references/architecture-contract.md para cada build, redesign ou mudança de arquitetura.
• Leia references/code-architecture.md antes de criar pastas, contratos, serviços, adaptadores ou ações de servidor.
• Leia references/dependency-matrix.md antes de instalar, atualizar ou remover dependências.
• Para um novo aplicativo, siga references/build-playbook.md.
• Para novas rotas, tipos de conteúdo, ilhas, arquivos, produtos de loja ou migrações, siga references/evolve-playbook.md.
• Antes da aceitação ou liberação, siga references/quality-gates.md.

Templates reutilizáveis vivem em assets/templates/. Comece a partir deles apenas quando corresponderem à arquitetura escolhida. Não copie todos os templates cegamente.

Invariantes inegociáveis

1. Mantenha a composição da página e o conteúdo principal em Componentes de Servidor por padrão.
2. Coloque use client na menor folha viável. Anime filhos renderizados no servidor através de wrappers de cliente quando possível.
3. Trate contratos de dados TypeScript como a fonte da verdade para cada entidade de conteúdo, registro de metadados, galeria e entrada de sitemap.
4. Dê a cada interação de overlay uma rota real que funcione sem estado de cliente, JavaScript ou hash.
5. Use comportamento HTML nativo primeiro: links, botões, formulários, <dialog>, gerenciamento de foco e histórico do navegador.
6. Mantenha segredos em módulos exclusivos do servidor. Apenas identificadores públicos podem usar NEXT_PUBLIC_*.
7. Quando houver comércio, mantenha preços, decisões de direito, confirmação de pagamento e downloads protegidos no servidor.
8. Respeite prefers-reduced-motion, navegação por teclado, foco visível, cabeçalhos semânticos e legibilidade sem script.
9. Mantenha o conteúdo de uma rota fora do pacote inicial de cliente de outra rota. Passe pequenos resumos do servidor quando um shell de cliente precisar de uma contagem ou rótulo.
10. Use um monólito modular com adaptadores de rota finos, módulos de funcionalidade próprios, portas explícitas e um único limite de composição.
11. Prefira dependências estáveis. Não inicie um novo aplicativo de produção com um build canary do React.

Stack padrão

Use as versões exatas validadas na matriz de dependência, a menos que o site tenha um motivo documentado para diferir.

• Node 26 LTS family e pnpm.
• Next.js App Router, React, React DOM, TypeScript.
• Tailwind CSS 4 para tokens, reset e layout utilitário.
• CSS Modules para composição de rota ou componente específica.
• Motion para orquestração e gestos React.
• Dialog nativo, Canvas, SVG, CSS e Web Animations API para interações onde são suficientes.
• Ícones Lucide importados individualmente.
• Zod para limites de conteúdo e entrada externa.
• Vercel para implantação, análise e entrega de imagens.
• Stripe Embedded Checkout e ações de servidor quando o comércio for necessário.

Sequência de trabalho

1. Inventarie as superfícies públicas: páginas de destino, índices de conteúdo, rotas de detalhe, caminhos de conversão, rotas legais, pesquisa, arquivo e comércio.
2. Congele o manifesto de rotas e o mapa de limites de cliente antes da implementação.
3. Atribua proprietários de funcionalidades, portas, adaptadores de rota e adaptadores externos antes de criar arquivos.
4. Modele entidades de conteúdo e mídia necessária antes de construir seções.
5. Estabeleça tokens globais, tipografia, espaçamento, estados, comportamento de movimento reduzido e convenções de imagem.
6. Construa o shell do servidor, navegação, fallbacks de rota e metadados SEO.
7. Adicione ilhas de cliente uma de cada vez. Registre por que cada uma deve ser do lado do cliente.
8. Construa overlays com dialog nativo e estado de URL. Adicione a rota canônica da página ao mesmo tempo.
9. Adicione visuais complexos após seus dados, fallback, comportamento de movimento reduzido e limites de desempenho serem definidos.
10. Adicione CMS, comércio, contas ou persistência apenas quando o modelo operacional exigir.
11. Execute a verificação de limites de arquitetura, auditoria estrutural, testes focados, portões de qualidade e aceitação de visualização de produção.
12. Relate comportamento implementado, evidências verificadas e limitações não verificadas separadamente.

Regras de decisão

• Use transições CSS para hover, foco, press, revelação, marquee e mudanças simples de estado.
• Use Motion para variantes coordenadas, transições de layout, arrastar, presença e orquestração vinculada a rolagem.
• Use Canvas ou WebGL apenas quando o visual não puder ser expresso de forma confiável com DOM, SVG e CSS. Adicione pausa de visibilidade, limites DPR, limpeza, comportamento de movimento reduzido e um fallback estático.
• Mantenha coleções de conteúdo renderizadas no servidor. Envie apenas contagens, rótulos ou registros selecionados para um shell de overlay do cliente.
• Use um <dialog> nativo para prévias e painéis quando o mesmo conteúdo também tiver uma página canônica. Use uma rota dedicada para conteúdo profundo, longo ou vinculado independentemente.
• Use conteúdo de código validado para uma equipe pequena que libera com o aplicativo. Introduza um CMS por trás de um adaptador de repositório quando editores precisarem de publicação independente.
• Use uma sessão Stripe sem estado quando a loja precisar apenas de compra imediata e download. Adicione um banco de dados e webhooks verificados quando o produto precisar de direitos, reembolsos, contas, histórico de pedidos ou novas tentativas.
• Adicione Radix, shadcn ou outra biblioteca de componentes somente após identificar a primitiva que ela possui. Elementos nativos e primitivas de propriedade do site são a base.
• Trate portfólios, arquivos e lojas como módulos. Eles reutilizam os contratos principais de conteúdo, rota, estilo, movimento e segurança.

Artefatos de build obrigatórios

Crie e mantenha estes artefatos de nível de site:

• docs/architecture.md: mapa de rotas, limites de cliente, propriedade de conteúdo, serviços externos e orçamentos de desempenho.
• src/features/*/domain e src/features/*/application: contratos e capacidades validados.
• src/platform/*: adaptadores externos e a raiz de composição exclusiva do servidor.
• src/shared/*: contratos e primitivas de design comprovados entre funcionalidades.
• src/components/*: composição de servidor e ilhas de cliente com nomes explícitos.
• src/app/*: páginas, layouts, metadados, sitemap, robots e manipuladores de rota.
• .env.example: nomes e finalidade, nunca segredos reais.
• Testes para validação de conteúdo, máquinas de estado do cliente, ações de servidor e jornadas críticas do navegador.
• Uma lista de verificação de liberação com evidências de visualização, navegador, acessibilidade, desempenho, SEO e comércio condicional.

Auditoria estrutural

Execute a verificação de limites de arquitetura e a auditoria de pacotes após o scaffold e antes da liberação:

pnpm arch:check
node scripts/audit_site.mjs --root /path/to/app

Use --strict no CI quando avisos devem falhar. O script verifica presença de dependências, estrutura de rota e conteúdo, perigos de segredo cliente/servidor, salvaguardas de dialog e movimento, testes, arquivos SEO e exposição de source-map. Ele complementa os testes e não os substitui.

Contrato de conclusão

Uma build está completa apenas quando:

• o mapa de rota e limites corresponde à implementação;
• o grafo de dependências é acíclico e arch:check passa;
• as rotas usam APIs públicas de funcionalidades e a raiz de composição possui a fiação;
• o aplicativo compila sem surpresas de canary ou dependências pares;
• o conteúdo crítico aparece no HTML do servidor;
• overlays, menus e caminhos de teclado funcionam e restauram o foco;
• fallbacks de movimento reduzido e sem script são verificados;
• metadados, sitemap, robots, URLs canônicas e imagens sociais estão presentes;
• os pacotes JS da rota inicial e os payloads de imagem permanecem dentro dos orçamentos documentados;
• comércio, quando presente, usa preços de propriedade do servidor, confirmação do lado do servidor e downloads protegidos;
• evidências de visualização e produção são registradas separadamente.