Arquitectura de Sitio Interactivo

¿Qué hace Arquitectura de Sitio Interactivo?

Resultado

Crear un sitio Next.js público y de producción cuyo contenido, narrativa, identidad visual y calidad de interacción importen. Esta es una arquitectura universal para sitios centrados en contenido: sitios de marca y marketing, sitios SaaS y de producto, páginas de lanzamiento, propiedades editoriales, portafolios, comunidades, conferencias, sitios con forma de documentación y exhibiciones inmersivas.

El núcleo es fijo:

• contenido renderizado en el servidor;
• islas de cliente estrechas;
• contratos de contenido validados;
• tokens de diseño y movimiento compartidos;
• comportamiento nativo del navegador;
• SEO y accesibilidad en la respuesta del servidor;
• presupuestos de rendimiento por ruta.

Selecciona los módulos que el producto necesita:

Módulo	Úsalo cuando
Colección y detalle de contenido	El sitio tiene proyectos, artículos, productos, personas, eventos o registros similares
Portafolio o casos de estudio	La organización necesita prueba a través del trabajo
Archivo inmersivo	La exploración visual es una superficie de producto principal
Tienda	El sitio vende productos digitales o físicos
Adaptador CMS	Los editores publican de forma independiente a los lanzamientos
Formulario de contacto	Un enlace de correo o calendario es insuficiente

No fuerces módulos opcionales en un sitio que no los necesita.

Los perfiles típicos reutilizan el mismo núcleo:

• SaaS o producto: página de inicio, oferta, características, colección de contenido, docs o changelog.
• Marca o lanzamiento: narrativa de campaña, revelación de producto, lista de espera, prueba social.
• Editorial: índice de colección, detalle de artículo, autores, temas, búsqueda.
• Comunidad o conferencia: oradores, horario, sesiones, lugar, entradas.
• Portafolio: índice de proyectos, detalle de caso, archivo visual, contacto.
• Comercio: catálogo, detalle de producto, pago, descarga o cumplimiento.

Leer antes de actuar

• Lee references/architecture-contract.md para cada compilación, rediseño o cambio de arquitectura.
• Lee references/code-architecture.md antes de crear carpetas, contratos, servicios, adaptadores o acciones del servidor.
• Lee references/dependency-matrix.md antes de instalar, actualizar o eliminar dependencias.
• Para una nueva aplicación, sigue references/build-playbook.md.
• Para nuevas rutas, tipos de contenido, islas, archivos, productos de tienda o migraciones, sigue references/evolve-playbook.md.
• Antes de la aceptación o lanzamiento, sigue references/quality-gates.md.

Las plantillas reutilizables viven en assets/templates/. Úsalas solo cuando coincidan con la arquitectura elegida. No copies cada plantilla a ciegas.

Invariantes no negociables

1. Mantén la composición de página y el contenido principal en Componentes del Servidor por defecto.
2. Coloca use client en la hoja más pequeña viable. Anima los hijos renderizados en el servidor a través de envoltorios de cliente cuando sea posible.
3. Trata los contratos de datos de TypeScript como la fuente de verdad para cada entidad de contenido, registro de metadatos, galería y entrada de sitemap.
4. Dale a cada interacción de superposición una ruta real que funcione sin estado de cliente, JavaScript o un hash.
5. Usa el comportamiento HTML nativo primero: enlaces, botones, formularios, <dialog>, gestión de enfoque e historial del navegador.
6. Mantén los secretos en módulos solo para servidor. Solo los identificadores públicos pueden usar NEXT_PUBLIC_*.
7. Cuando exista comercio, mantén los precios, las decisiones de derecho, la confirmación de pago y las descargas protegidas en el servidor.
8. Respeta prefers-reduced-motion, la navegación por teclado, el enfoque visible, los encabezados semánticos y la legibilidad sin script.
9. Mantén el contenido de una ruta fuera del paquete de cliente inicial de otra ruta. Pasa pequeños resúmenes desde el servidor cuando un shell de cliente necesite un conteo o etiqueta.
10. Usa un monolito modular con adaptadores de ruta delgados, módulos de características propios, puertos explícitos y un único límite de composición.
11. Prefiere dependencias estables. No inicies una nueva aplicación de producción en una compilación canary de React.

Stack predeterminado

Usa las versiones validadas exactas en la matriz de dependencias a menos que el sitio tenga una razón documentada para diferir.

• Familia Node 26 LTS y pnpm.
• Next.js App Router, React, React DOM, TypeScript.
• Tailwind CSS 4 para tokens, reinicio y diseño de utilidades.
• Módulos CSS para composición específica de ruta o componente.
• Motion para orquestación de React y gestos.
• Dialog nativo, Canvas, SVG, CSS y API de animaciones web para interacciones donde sean suficientes.
• Iconos de Lucide importados individualmente.
• Zod para límites de contenido y entradas externas.
• Vercel para despliegue, análisis y entrega de imágenes.
• Stripe Embedded Checkout y acciones del servidor cuando se requiera comercio.

Secuencia de trabajo

1. Inventaria las superficies públicas: páginas de aterrizaje, índices de contenido, rutas de detalle, caminos de conversión, rutas legales, búsqueda, archivo y comercio.
2. Congela el manifiesto de rutas y el mapa de límites de cliente antes de la implementación.
3. Asigna propietarios de funciones, puertos, adaptadores de ruta y adaptadores externos antes de crear archivos.
4. Modela las entidades de contenido y los medios requeridos antes de construir secciones.
5. Establece tokens globales, tipografía, espaciado, estados, comportamiento de movimiento reducido y convenciones de imagen.
6. Construye el shell del servidor, la navegación, los fallbacks de ruta y los metadatos SEO.
7. Agrega islas de cliente una por una. Registra por qué cada una debe ser del lado del cliente.
8. Construye superposiciones con dialog nativo y estado de URL. Agrega la ruta de página canónica al mismo tiempo.
9. Agrega visuales complejos después de que sus datos, fallback, comportamiento de movimiento reducido y límites de rendimiento estén definidos.
10. Agrega CMS, comercio, cuentas o persistencia solo cuando el modelo operativo lo requiera.
11. Ejecuta la verificación de límites de arquitectura, auditoría estructural, pruebas enfocadas, puertas de calidad y aceptación de vista previa de producción.
12. Informa el comportamiento implementado, la evidencia verificada y las limitaciones no verificadas por separado.

Reglas de decisión

• Usa transiciones CSS para hover, focus, press, reveal, marquee y cambios de estado simples.
• Usa Motion para variantes coordinadas, transiciones de diseño, arrastre, presencia y orquestación vinculada al desplazamiento.
• Usa Canvas o WebGL solo cuando el visual no se pueda expresar de manera confiable con DOM, SVG y CSS. Agrega pausa de visibilidad, límites de DPR, limpieza, comportamiento de movimiento reducido y un fallback estático.
• Mantén las colecciones de contenido renderizadas en el servidor. Envía solo conteos, etiquetas o registros seleccionados a un shell de superposición de cliente.
• Usa un <dialog> nativo para vistas previas y hojas cuando el mismo contenido también tenga una página canónica. Usa una ruta dedicada para contenido profundo, largo o vinculado de forma independiente.
• Usa contenido de código validado para un equipo pequeño que lanza con la aplicación. Introduce un CMS detrás de un adaptador de repositorio cuando los editores necesiten publicación independiente.
• Usa una sesión de Stripe sin estado cuando la tienda solo necesite compra y descarga inmediatas. Agrega una base de datos y webhooks verificados cuando el producto necesite derechos, reembolsos, cuentas, historial de pedidos o reintentos.
• Agrega Radix, shadcn u otra biblioteca de componentes solo después de identificar la primitiva que posee. Los elementos nativos y las primitivas propias del sitio son la base.
• Trata los portafolios, archivos y tiendas como módulos. Reutilizan los contratos principales de contenido, ruta, estilo, movimiento y seguridad.

Artefactos de compilación requeridos

Crea y mantén estos artefactos a nivel de sitio:

• docs/architecture.md: mapa de rutas, límites de cliente, propiedad de contenido, servicios externos y presupuestos de rendimiento.
• src/features/*/domain y src/features/*/application: contratos y capacidades validadas.
• src/platform/*: adaptadores externos y la raíz de composición solo para servidor.
• src/shared/*: contratos y primitivas de diseño probados entre funciones.
• src/components/*: composición de servidor e islas de cliente con nombres explícitos.
• src/app/*: páginas, layouts, metadatos, sitemap, robots y manejadores de rutas.
• .env.example: nombres y propósito, nunca secretos reales.
• Pruebas para validación de contenido, máquinas de estado de cliente, acciones del servidor y recorridos críticos del navegador.
• Una lista de verificación de lanzamiento con evidencia de vista previa, navegador, accesibilidad, rendimiento, SEO y comercio condicional.

Auditoría estructural

Ejecuta la verificación de límites de arquitectura y la auditoría empaquetada después del andamiaje y antes del lanzamiento:

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

Usa --strict en CI cuando las advertencias deban fallar. El script verifica la presencia de dependencias, la estructura de rutas y contenido, los peligros de secretos de cliente/servidor, las salvaguardas de dialog y motion, las pruebas, los archivos SEO y la exposición del mapa fuente. Complementa las pruebas y no las reemplaza.

Contrato de finalización

Una compilación está completa solo cuando:

• el mapa de rutas y límites coincide con la implementación;
• el gráfico de dependencias es acíclico y arch:check pasa;
• las rutas usan APIs públicas de funciones y la raíz de composición posee el cableado;
• la aplicación se compila sin sorpresas de canary o dependencias pares;
• el contenido crítico aparece en el HTML del servidor;
• las superposiciones, menús y rutas de teclado funcionan y restauran el enfoque;
• los fallbacks de movimiento reducido y sin script están verificados;
• los metadatos, sitemap, robots, URLs canónicas e imágenes sociales están presentes;
• el JS de la ruta inicial y las cargas de imágenes se mantienen dentro de los presupuestos documentados;
• el comercio, cuando está presente, usa precios propiedad del servidor, confirmación del lado del servidor y descargas protegidas;
• la evidencia de vista previa y producción se registran por separado.