Architecture

La version courte

Il existe une seule source de vérité — un corpus de fichiers Markdown dans git — et tout le reste est généré à partir de celle-ci ou la lit : le site web en sept langues, les fichiers pour les agents, l’assistant Ask Jenks, l’API REST, les serveurs MCP et la CLI.

Le corpus

content/corpus/ contient un fichier Markdown par expérience, projet, rôle communautaire et entrée d’éducation, chacun avec du frontmatter YAML (dates, tags, lentilles de rôle, résultats clés, compétences, liens de preuve) et un corps long. À côté se trouvent le profil principal, les capacités, les certifications, les conférences, la vision du monde, les lentilles de rôle et les compétences de l’assistant. Les faits ont été assemblés à partir des CV de Jenks, de LinkedIn, de Linktree et de sa page d’orateur, avec des conflits résolus de manière conservatrice.

Garder le corpus dans git signifie que chaque changement est un commit : révisable, attribuable et réversible.

Le compilateur

scripts/build-corpus.mjs lit le corpus, valide chaque fichier contre un seul schéma (scripts/corpus-schema.mjs) et le compile en un corpus JSON unique plus les fichiers d’agent /llms-full.txt et /experience.json. Des tags ou lentilles inconnus, de mauvaises dates, des images manquantes ou une section manquante arrêtent la construction. L’API d’administration exécute la même validation avant de valider un commit, de sorte qu’une mauvaise édition — par une personne ou une IA — est refusée avant qu’elle ne puisse casser quoi que ce soit.

Médias

Les photos, clips vidéo et PDF ne sont pas dans git. Ils sont téléversés via les interfaces d’administration vers un bucket Cloudflare R2 partagé par le développement et la production, et servis par le Worker à /media/<year>/<month>/<name>-<fingerprint>.<ext> avec une mise en cache d’un an. Le contenu y fait référence par ce chemin ; l’API d’administration vérifie que chaque fichier référencé existe avant de valider un commit.

Le site web

Le site est un export statique Next.js servi par Cloudflare Workers Static Assets. Un petit Worker en frontal gère les redirections (les hôtes jenksguo.com et www → jenksguo.xyz), les en-têtes de sécurité et les API.

Le site a deux adresses qui affichent toujours la même chose. https://jenksguo.pages.dev est l’adresse canonique, sur les CV et les QR codes : les réseaux d’entreprise bloquent souvent les domaines nouvellement enregistrés, et pages.dev est ancien et largement autorisé. https://jenksguo.xyz est un miroir. L’adresse pages.dev est un projet Cloudflare Pages (mirror/) dont le seul code transfère chaque requête vers le Worker du site, ainsi un seul déploiement met à jour les deux adresses et il n’y a rien à synchroniser. L’anglais se trouve à / ; les six autres langues à /zh, /zh-hant, /ja, /fr, /es et /eo. Chaque entrée a sa propre page dans chaque langue.

L’assistant Ask Jenks

L’assistant est un agent utilisateur d’outils plutôt qu’un long prompt. Son prompt système ne contient que le profil principal et un index d’une ligne de chaque entrée, lentille et compétence. Lorsqu’il a besoin de détails, il appelle des outils :

• load_skill — un mode d’emploi pour le type de question (adéquation au rôle, cadrage de conseil, transformation IA, histoires STAR, gouvernance, navigation de carrière…),
• get_entries — des descriptions complètes par slug,
• list_entries — filtrées par tag, lentille ou type,
• search_corpus — recherche par mots-clés.

Cette divulgation progressive maintient les réponses ancrées dans l’ensemble du corpus sans un énorme prompt. Les modèles sont utilisés via OpenRouter.

Une seule spécification, quatre surfaces

src/spec.js définit une fois chaque outil public et d’administration : nom, description, schéma d’entrée, route REST et commande CLI. Il en découle :

• les serveurs MCP distants (/mcp, /mcp/admin),
• l’API REST (/api/v1/*, /api/admin/*),
• la CLI jenks et son mode MCP local (jenks mcp),
• la documentation de référence et /openapi.json.

Modifiez un outil en un seul endroit et chaque surface suit, de sorte que la documentation ne peut pas diverger du comportement.

Pipeline de publication

Les éditions d’administration sont des commits effectués via l’API GitHub. Chaque push déclenche la CI :

1. compiler et valider le corpus,
2. retraduire uniquement les entrées qui ont changé dans les six autres langues (les traductions sont mises en cache par un hachage de leur source anglaise ; un glossaire figé fixe les titres et les noms de lentilles),
3. construire le site et les fichiers d’agent,
4. déployer — main vers https://jenksguo.pages.dev, dev vers https://dev.jenksguo.xyz (non indexé).

Les binaires CLI pour macOS, Linux et Windows sont publiés sous /downloads.

Pourquoi c’est conçu ainsi

Un site personnel est petit, mais il est lu par des personnes, des moteurs de recherche et de plus en plus par des agents, en plusieurs langues, et édité par une IA aussi souvent qu’à la main. Une source unique validée avec des surfaces générées est la conception la plus simple qui maintienne tout cela cohérent.