Arquitectura

El sitio es una aplicación Next.js 16 (App Router) construida como HTML estático en tiempo de build, estilizada con el lenguaje de diseño YuTheme y desplegada en Vercel. No hay runtime de servidor.

Stack

• Next.js 16 (App Router, generación estática)
• React 19
• TypeScript
• pnpm (gestor de paquetes, versión fijada vía packageManager)
• Monorepo Turborepo (apps/, packages/)
• next-intl para los siete idiomas, localePrefix: as-needed
• Tokens y convenciones editoriales YuTheme (ver design.md)
• Iconos Lucide vía lucide-react
• Fuentes: Geist Variable y Geist Mono Variable vía next/font/local

El único JavaScript de cliente es una pequeña cantidad de hidratación: el menú móvil del header, el scrollspy, el scroll suave de anclas y las revelaciones de scroll.

Estructura

apps/web/src/
  app/
    [locale]/
      layout.tsx            caparazón del documento, fuentes, metadata, JSON-LD
      page.tsx              home de una sola página
      docs/page.tsx         índice de documentación
      docs/[slug]/page.tsx  páginas individuales de documentación
      globals.css           tokens YuTheme, estilos base, motion
    sitemap.ts              sitemap para todos los idiomas
    robots.ts
  components/
    Analytics.tsx           hook Umami, activado por env, inerte por defecto
    Footer.tsx
    Header.tsx              header fijo, scrollspy, panel móvil
    Icon.tsx                mapa de iconos Lucide, nombres tipados
    Reveal.tsx              revelación de scroll vía IntersectionObserver
    sections/
      Hero.tsx              titular + tarjeta terminal
      About.tsx
      WhatIDo.tsx           cuadrícula de tarjetas
      HowIWork.tsx
      WhereILive.tsx
      SelectedWork.tsx      lista de trabajo público
  data/site.ts              constantes del sitio: URLs, navegación
  i18n/                     routing, config de request, navegación tipada
  lib/docs.ts               pipeline de markdown de las páginas de docs
packages/
  content/                  fuentes de docs/, leídas por idioma con fallback EN
  i18n/                     lista de idiomas + mensajes de los siete locales
  ui/styles/                CSS YuTheme canónico, referencia de tokens

Localización

• Idiomas: en (por defecto, sin prefijo), pt, es, fr, de, ja, zh-CN.
• El copy de interfaz vive en packages/i18n/messages/<locale>.json.
• La documentación vive en packages/content/docs/<locale>/; cuando un idioma no tiene un archivo, se sirve la versión en inglés como fallback.
• Las rutas son estáticas: cada idioma y cada slug de doc se prerenderiza en el build mediante generateStaticParams.

Pipeline de docs

Las páginas de documentación leen la carpeta packages/content/docs/ a través de packages/content/src/index.ts:

• cada doc es un archivo Markdown con frontmatter: title, description, order, updated;
• la app lo renderiza con remark/rehype (GFM, headings con slug, autolinks, HTML saneado) en /docs/<slug>, con índice en /docs;
• @ellamizuki/content se mantiene externo al bundle de la app (serverExternalPackages) para que las lecturas de filesystem funcionen en producción.

Como la colección lee la misma carpeta versionada en el repositorio, las docs se mantienen sincronizadas: una fuente de verdad, dos vistas (página del sitio y archivos del repo).

Flujo de datos

• En el build: Next.js prerenderiza /, /docs, /docs/* para cada idioma.
• El contenido está prerenderizado; no hay servidor, API ni datos en runtime.
• Analytics (Umami) solo se inyecta cuando NEXT_PUBLIC_UMAMI_SRC y NEXT_PUBLIC_UMAMI_WEBSITE_ID están definidas en el build.

Convenciones

• HTML semántico con un único h1 por página.
• Headings de sección en orden (h2 luego h3), sin saltar niveles.
• Los enlaces externos abren en una nueva pestaña con rel="noopener noreferrer".
• Los enlaces renderizados por next-intl nunca reciben un href ya prefijado; el prefijo del idioma siempre lo añaden los helpers de navegación.
• El reduced motion se respeta en todas partes: shimmer, revelaciones y transiciones están controlados por prefers-reduced-motion.