Portafolio: Cyberpunk

Un portafolio interactivo con una identidad de glitch digital, construido con Next.js 16, React 19, TypeScript, Tailwind CSS 4 y MDX.

DEMO EN VIVO · REPOSITORIO PRIVADO

Descripción General

• Rol: Creador, desarrollador full-stack e ingeniero creativo.
• Propósito: Presentar trabajo, experiencia y criterio técnico mediante una experiencia editorial e interactiva.
• Audiencia: Reclutadores, responsables de ingeniería, clientes y colegas desarrolladores.
• Stack principal: Next.js 16 App Router, React 19, TypeScript, Tailwind CSS 4, MDX, next-intl, Framer Motion, ondas Canvas personalizadas con distorsión estilo Perlin, Three.js, React Three Fiber, integración de IA neutral respecto al proveedor, MCP/OAuth, Node.js 24 LTS y Vercel.
• Contenido: Datos estáticos y documentos MDX localizados en nueve idiomas.
• Despliegue: Vercel con Fluid compute.
• Resultado clave: Un producto público que demuestra una arquitectura creativa y mantenible con contenido localizado.
• Resumen: La identidad glitch, la lectura editorial y las integraciones controladas funcionan como una experiencia coherente.

El Problema

• Desafío: Comunicar personalidad y profundidad técnica sin ocultar la información importante.
• Audiencia: Reclutadores, responsables de ingeniería, clientes y desarrolladores que revisan tanto diseño como arquitectura.
• Restricciones: La experiencia debía ser legible en pantallas pequeñas, respetar reduced motion, sostener nueve idiomas y proteger los límites de las integraciones.
• Un portafolio necesita comunicar personalidad y profundidad técnica sin ocultar la información importante.
• El sitio debía ofrecer una navegación visual expresiva y seguir siendo legible en pantallas pequeñas.
• La información de proyectos debía poder ampliarse sin convertir cada página en código de interfaz.
• Las funciones con IA y las integraciones externas debían estar separadas de la presentación del contenido.
• La internacionalización debía conservar rutas, metadatos y experiencia coherentes para cada idioma.
• La privacidad del repositorio requería describir la arquitectura sin publicar su código fuente.

Enfoque

• Arquitectura: Next.js App Router organiza rutas localizadas, documentos renderizados en servidor y handlers; los shells interactivos permanecen en el cliente.
• Decisiones clave:
  • Contenido y rutas de nueve idiomas: next-intl resuelve rutas y mensajes, y cada proyecto conserva un MDX localizado con fallback documentado al inglés.
  • Interacción Canvas y 3D: Ondas Canvas personalizadas con distorsión estilo Perlin, Framer Motion y un hero focalizado de Three.js/React Three Fiber añaden movimiento expresivo sin convertir todo el producto en una escena 3D.
  • FUI y terminal diagnóstico: Textura CRT, scanlines, tipografía glitch y lecturas de estado crean una identidad de interfaz futurista sin perder jerarquía legible.
  • Voz y doblaje opcionales: La voz local, el popup de doblaje y su secuenciación siguen la configuración del usuario y la compatibilidad del navegador.
  • Coordinación de capas: Pantalla de arranque, navegación, cursor, scanlines, chat, popup de doblaje y hero 3D se coordinan con stacking deliberado, no con un número fijo de capas.
  • Diseño del asistente Oz: /api/chat usa enrutamiento neutral entre servicios con principal y respaldo, contexto de datos estáticos del portafolio y MDX profundo, y herramientas de interfaz explícitas.
  • Límites de cliente, servidor y estado: Los providers aíslan tema, internacionalización y música; las preferencias de chat viven localmente y el store de filtros tiene una responsabilidad estrecha.
  • MCP y OAuth: Las herramientas de solo lectura usan OAuth 2.1, PKCE S256 y el scope portfolio.read.
• Trade-offs: Se prefieren Canvas y 3D puntuales a una presentación enteramente 3D, y la voz del navegador es una mejora opcional, no un servicio de voz del servidor.
• Flujo de datos: La entrada llega a /api/chat, recibe contexto de datos estáticos del portafolio y MDX profundo, y devuelve una respuesta en streaming o una acción de interfaz; los navegadores compatibles pueden usar voz local opcional.
• El App Router organiza las pantallas, los handlers y los documentos de infraestructura en una única aplicación.
• next-intl resuelve las rutas localizadas y carga mensajes para las nueve configuraciones regionales.
• Las secciones del portafolio consumen datos tipados y los casos de estudio se escriben en MDX.
• Las capas interactivas se aíslan en componentes cliente y proveedores cuando necesitan estado del navegador.
• El lenguaje visual combina tipografía de alto contraste, paneles terminales, ruido, líneas de exploración y detalles glitch.
• El chatbot se comunica con un handler del servidor para que las claves y las reglas del proveedor no lleguen al navegador.

Resultados

• Resultado: El sitio ofrece una orientación rápida y una explicación profunda de los sistemas que lo sostienen.
• Calidad y validación: ESLint, comprobación de tipos y build de producción son puertas de calidad reproducibles.
• Controles de seguridad: El chat aplica límites firmados y de ritmo, mientras MCP usa scopes de solo lectura y códigos de autorización de un solo uso.
• Comparación y evolución: La experiencia amplía el anterior Portfolio: Glass hacia una base modular capaz de sostener narrativa localizada y acceso de agentes.
• Impacto: Demuestra frontend creativo junto con decisiones de contenido, integración, seguridad y despliegue mantenibles.
• El proyecto funciona como sitio público y como demostración mantenible de una arquitectura Next.js actual.
• El contenido principal está disponible en inglés, tagalo, alemán, español, francés, árabe, coreano, japonés y chino.
• Los proyectos pueden incluir portada, texto largo, tablas y componentes MDX compartidos.
• La interfaz ofrece navegación, cursor personalizado en dispositivos con puntero preciso y controles de música opcionales.
• Las rutas operativas exponen documentación legible para personas y contratos útiles para herramientas.

Profundización Técnica

• Detalles destacados: La textura tipo CRT, la tipografía glitch, Canvas, un hero 3D focalizado, controles de música y contenido localizado comparten responsabilidades sin un contenedor global excesivo.
• Verificación: Lint, tipos y build de producción son verificaciones repetibles; las ramas responsive, reduced-motion y coarse-pointer se revisan en cambios de interfaz.
• Optimizaciones: Los shells solo de cliente aíslan capacidades del navegador, y MDX, datos y componentes modulares evitan cargar interacción donde no es necesaria.
• Calidad de código: Los tipos TypeScript, handlers organizados, providers enfocados, stores estrechos y módulos de servicio o seguridad aclaran la propiedad del código.
• Enlaces y referencias: Consultar components/sections, components/ui, components/chatbot, components/providers, content/projects, messages, data, lib/mcp, lib/security, lib/services y stores.
• El endpoint /api/chat valida solicitudes del mismo origen, aplica el contexto del portafolio y delega al servicio de chatbot. Cuando se activan los controles contra abuso, una cookie temporal de bloqueo firmada transmite la restricción, no la solicitud en sí.
• Un proveedor de IA principal atiende las solicitudes y una alternativa toma el relevo cuando la política de servicio lo requiere.
• La ruta /api/contact entrega los mensajes del formulario mediante la configuración SMTP del entorno.
• El reproductor usa rutas de Spotify para iniciar sesión, recibir el callback y consultar la pista actual.
• /api/gallery/[slug] es una superficie limitada por tasa para media y galerías de proyectos compatibles.
• Las acciones aprobadas de Oz pueden abrir una galería de proyecto cuando está habilitada y es compatible, sin presentarla como acción universal en móvil.
• La integración MCP publica HTTP streamable, compatibilidad SSE heredada y una comprobación de salud.
• OAuth 2.1 con PKCE S256 protege el acceso de solo lectura de los clientes MCP.
• Los códigos de autorización de un solo uso utilizan Redis compatible con Upstash en Vercel cuando está disponible.
• Los proveedores de cliente delimitan los estados de tema, música, chatbot y shells que dependen del navegador.
• Los componentes de servidor preparan contenido y metadatos antes de que los widgets interactivos tomen el control.
• La accesibilidad se apoya en estructura semántica, controles etiquetados, foco utilizable y cursor desactivado para punteros gruesos.
• El middleware de internacionalización dirige las solicitudes a la configuración regional correspondiente.
• Los componentes de proyecto comparten convenciones de portada, encabezados y tablas mediante la capa MDX.
• Los metadatos de cada página se generan con el contexto de idioma y contenido disponible.
• La navegación usa los ayudantes de next-intl para conservar el prefijo regional correcto.
• Los tokens CSS evitan colores dispersos y permiten ajustar la identidad visual desde el sistema global.
• La pantalla de carga y la navegación se coordinan con el ciclo de interacción del documento.
• Los formularios validan el límite entre el cliente y el handler antes de enviar correo.
• Las rutas de salud ofrecen una comprobación limitada para los sistemas integrados.
• El contenido público se renderiza desde datos estáticos y MDX, sin depender de almacenamiento de proyectos en tiempo de ejecución.
• La configuración de secretos permanece en variables de entorno y nunca forma parte de MDX ni de mensajes cliente.
• Los comandos de calidad incluyen ESLint, comprobación de tipos y compilación de producción.
• El paquete bloquea Node.js 24 LTS con engines y un archivo .nvmrc.
• Los recursos de descubrimiento ayudan a clientes MCP y lectores automatizados a interpretar el sitio.
• Las mejoras visuales se diseñan para degradarse con elegancia cuando una capacidad no está disponible.
• El diseño responsive adapta jerarquía, espaciado y controles antes que reducir texto de forma arbitraria.

Reflexiones

• De forma diferente: Seguir simplificando los recorridos visuales más exigentes sin perder la personalidad editorial.
• Éxitos: Interfaz, narrativa localizada, asistencia, música y descubrimiento se perciben como un mismo producto.
• Lecciones: La interacción rica y las respuestas en streaming son sostenibles cuando contenido, navegador y servidor tienen límites claros.
• Un sistema visual intenso necesita dejar espacio suficiente para que el contenido siga siendo el protagonista.
• Mantener los límites entre datos estáticos, MDX, estado cliente y servicios de servidor reduce el coste de cambio.
• Las afirmaciones de rendimiento deben describir la práctica y las verificaciones reproducibles, no cifras fijas fuera de contexto.

Contribuciones

• Frontend y diseño: Diseñé el sistema visual, las secciones responsive, la composición tipo HUD, Canvas, el hero 3D y la presentación de contenido.
• IA y Oz: Construí la superficie de asistencia en streaming, el enrutamiento principal y de respaldo, el uso de contexto y las acciones de interfaz.
• Voz, capas y contenido: Implementé feedback local de voz y doblaje, coordinación de overlays, flujo MDX de nueve idiomas y fallback al inglés.
• MCP y seguridad: Implementé acceso de solo lectura, OAuth, discovery, validación same-origin del chat y el bloqueo temporal firmado separado.
• Interacción y animación: Ajusté movimiento, scroll, reduced-motion y comportamiento responsive para que los efectos no compitan con el contenido.
• Diseñé la dirección visual, las secciones del portafolio y los componentes reutilizables de la interfaz.
• Implementé el sistema de contenido MDX, el enrutamiento localizado y los metadatos por idioma.
• Integré el chatbot, el formulario de contacto, Spotify y la superficie MCP con límites de seguridad del servidor.

Arquitectura

• Estructura en capas: Los componentes de servidor resuelven locale y documento; los de cliente manejan interacción. Las rutas API aíslan chat, contacto, media y MCP.
• Módulos de funcionalidad:
• Presentación
  • src/components/sections/ reúne Hero, About, Experience, Skills, Projects, Contact y Certification.
  • src/components/ui/ contiene GlitchText, Waves, CustomCursor, HeroModel, SkillGraph y piezas visuales.
  • src/components/layout/ contiene navegación, pantalla de arranque y retorno al inicio.
• Contenido y estado
  • src/data/ define datos estáticos tipados y src/content/projects/ guarda los casos de estudio MDX.
  • src/messages/ mantiene los mensajes traducidos y src/i18n/ define locales y resolución de solicitudes.
  • src/stores/ y src/components/providers/ delimitan el estado compartido de la experiencia cliente.
• Servicios y rutas
  • src/lib/services/chatbot/ abstrae los servicios de IA y src/app/api/ expone los handlers.
  • src/app/.well-known/, openapi.json, llms.txt y llms-full.txt publican metadatos de integración.
• Gestión de estado: Theme, internacionalización y música viven en providers; las preferencias de Oz permanecen locales y el filtro de chat usa un store específico.
• Refactorización y mejoras: Los límites modulares permiten que rutas, contenido, servicios y componentes visuales evolucionen de manera independiente.

Estructura de rutas y sistemas

• Sitio localizado: /[locale] y /[locale]/projects/[slug] renderizan la página principal y cada estudio MDX.
• Oz, contacto y media: /api/chat, /api/chat/health, /api/contact, /api/gallery/[slug], /api/spotify/login, /api/spotify/callback y /api/spotify/now-playing atienden las funciones del sitio.
• Spotify: /api/spotify/login, /api/spotify/callback y /api/spotify/now-playing conectan el reproductor opcional.
• MCP y OAuth: /api/mcp, /api/mcp/message, /api/mcp/sse, /api/mcp/health y los documentos OAuth de /.well-known/ forman la superficie de agentes.
• Descubrimiento: /sitemap.xml, /robots.txt, /llms.txt, /llms-full.txt, /auth.md y /openapi.json describen el sitio para rastreadores y herramientas.

Demo

• Inicio editorial: La página de una sola sesión combina introducción, experiencia, habilidades, proyectos, certificaciones y contacto.
• Capas interactivas: El chatbot, el reproductor y el cursor se cargan como mejoras que respetan la capacidad del dispositivo.
• Estudios de proyecto: Cada ficha abre una narrativa MDX localizada con componentes de portada y tipografía consistente.
• Landing FUI digital: CRT, lecturas de estado terminales y detalles glitch conservan el contenido como prioridad.
• Feedback de voz y doblaje: El audio local opcional no es necesario para navegar o leer el sitio.
• Grids responsive y detalle localizado: Los bloques de contenido denso y los estudios de proyecto se adaptan al dispositivo y al idioma elegido.
• Descubrimiento para agentes: OAuth y documentos públicos describen acceso de solo lectura compatible con herramientas.

El sitio está publicado en franzdomingo.dev y este repositorio permanece privado.