Arquitectura

La versión corta

Hay una única fuente de verdad —un corpus de archivos Markdown en git— y todo lo demás se genera a partir de él o lo lee: el sitio web en siete idiomas, los archivos para agentes, el asistente Ask Jenks, la API REST, los servidores MCP y la CLI.

El corpus

content/corpus/ contiene un archivo Markdown por experiencia, proyecto, rol comunitario y formación, cada uno con frontmatter YAML (fechas, etiquetas, lentes de rol, resultados clave, habilidades, enlaces de prueba) y un cuerpo largo. A su lado están el perfil central, capacidades, credenciales, charlas, cosmovisión, las lentes de rol y las habilidades del asistente. Los hechos se reunieron a partir de los currículums de Jenks, LinkedIn, Linktree y su página de ponente, con los conflictos resueltos de forma conservadora.

Mantener el corpus en git significa que cada cambio es un commit: revisable, atribuible y reversible.

El compilador

scripts/build-corpus.mjs lee el corpus, valida cada archivo contra un único esquema (scripts/corpus-schema.mjs) y lo compila en un solo corpus JSON más los archivos de agente /llms-full.txt y /experience.json. Etiquetas o lentes desconocidos, fechas erróneas, imágenes que faltan o una sección ausente detienen la compilación. La API de administración ejecuta la misma validación antes de hacer commit, de modo que una mala edición —por una persona o una IA— se rechaza antes de que pueda romper nada.

Medios

Las fotos, videoclips y PDFs no están en git. Se suben a través de las interfaces de administración a un bucket de Cloudflare R2 compartido por desarrollo y producción, y los sirve el Worker en /media/<year>/<month>/<name>-<fingerprint>.<ext> con caché de un año. El contenido se refiere a ellos por esa ruta; la API de administración comprueba que cada archivo referenciado exista antes de hacer commit.

El sitio web

El sitio es una exportación estática de Next.js servida por Cloudflare Workers Static Assets. Un pequeño Worker delante maneja redirecciones (los hosts jenksguo.com y www → jenksguo.xyz), cabeceras de seguridad y las APIs.

El sitio tiene dos direcciones que siempre muestran lo mismo. https://jenksguo.pages.dev es la canónica, en CVs y códigos QR: las redes corporativas a menudo bloquean dominios recién registrados, y pages.dev es antiguo y ampliamente permitido. https://jenksguo.xyz es un espejo. La dirección pages.dev es un proyecto de Cloudflare Pages (mirror/) cuyo único código reenvía cada solicitud al Worker del sitio, por lo que un único deploy actualiza ambas direcciones y no hay nada que mantener en sincronía. El inglés vive en /; los otros seis idiomas en /zh, /zh-hant, /ja, /fr, /es y /eo. Cada entrada tiene su propia página en cada idioma.

El asistente Ask Jenks

El asistente es un agente que usa herramientas en lugar de un prompt largo. Su prompt del sistema contiene solo el perfil central y un índice de una línea de cada entrada, lente y habilidad. Cuando necesita detalle llama a herramientas:

• load_skill — un playbook para el tipo de pregunta (encaje de rol, dimensionamiento de consultoría, transformación de IA, historias STAR, gobernanza, navegación de carrera…),
• get_entries — desarrollos completos por slug,
• list_entries — filtrado por etiqueta, lente o tipo,
• search_corpus — búsqueda por palabra clave.

Esta revelación progresiva mantiene las respuestas ancladas en todo el corpus sin un prompt enorme. Los modelos se alcanzan a través de OpenRouter.

Una especificación, cuatro superficies

src/spec.js define cada herramienta pública y de administración una sola vez: nombre, descripción, esquema de entrada, ruta REST y comando de la CLI. De ahí salen:

• los servidores MCP remotos (/mcp, /mcp/admin),
• la API REST (/api/v1/*, /api/admin/*),
• la CLI jenks y su modo MCP local (jenks mcp),
• la documentación de referencia y /openapi.json.

Cambia una herramienta en un lugar y todas las superficies la siguen, de modo que la documentación no puede desviarse del comportamiento.

Pipeline de publicación

Las ediciones de administración son commits hechos a través de la API de GitHub. Cada push ejecuta CI:

1. compilar y validar el corpus,
2. retraducir solo las entradas que cambiaron a los otros seis idiomas (las traducciones se almacenan en caché por un hash de su fuente en inglés; un glosario fijo establece encabezados y nombres de lentes),
3. construir el sitio y los archivos de agente,
4. desplegar: main a https://jenksguo.pages.dev, dev a https://dev.jenksguo.xyz (no indexado).

Los binarios de la CLI para macOS, Linux y Windows se publican en /downloads.

Por qué tiene esta forma

Un sitio personal es pequeño, pero lo leen personas, motores de búsqueda y, cada vez más, agentes, en varios idiomas, y lo edita una IA tan a menudo como a mano. Una única fuente validada con superficies generadas es el diseño más simple que mantiene todo eso consistente.