Intégrer le Quiz HP dans le hub plutôt que sur un sous-domaine

Au départ, je pensais déployer le Quiz HP comme service séparé : sous-domaine, repo à part, isolation totale. En creusant, la plupart des arguments techniques ne tenaient pas. Voici pourquoi tout vit dans le même projet Next.js que le portfolio.

Article précédent : vision et scope du quiz.

Ce qui a changé par rapport au hub d'origine

ADR-002 disait « pas de base de données » — c'était vrai pour le portfolio seul. HPQ amende ce choix : Neon Postgres pour le stock de questions, Drizzle comme ORM, routes API serverless sur Vercel.

Le site n'est plus 100 % statique. Il héberge une section à état dédiée au quiz et des scripts de population locaux (Gemini ne tourne pas en prod pour jouer).

Décision retenue

• Hébergement — même projet Next.js, même déploiement Vercel
• URL — route dédiée sous le domaine principal (pas de sous-domaine)
• Code — isolé par domaine dans app, lib et components
• Extraction future — possible si le projet grossit

Pourquoi pas un service séparé ?

Arguments initiaux écartés :

• Isolation Vercel — les fonctions serverless sont déjà isolées entre routes dans un même projet
• Cron indépendant — un Vercel Cron Job fonctionne aussi bien dans le hub
• Stack différente — non : Next.js dans les deux cas

Ce qu'on gagne en restant dans le portfolio :

• Un seul repo, un seul déploiement, previews PR automatiques
• Réutilisation du design system (thème HP dédié — prochain article)
• Pas de DNS, pas de proxy, pas de communication cross-service

Risques acceptés

Un bug de build dans le code HPQ peut bloquer le déploiement de tout le site — blog et CV inclus. Mitigation : CI, PR, previews avant merge sur main.

Une variable d'env mal configurée sur Neon peut impacter le quiz sans toucher aux pages statiques — d'où une route health API pour diagnostiquer prod.

Organisation concrète

Route group dédié dans l'App Router, avec pages setup / play / results, routes API start-stock-health, composants UI, lib métier (db, gemini, populate), fiches MDX de grounding par film, scripts CLI populate/clear, et thème CSS scoped (Tailwind v4 — pas dans globals.css).

Layout quiz sans header/footer turquoise : entrée visuelle claire dans l'univers HP.

Alternatives écartées

• Sous-domaine dédié — deux déploiements, duplication design system
• Domaine séparé — coût + perte de l'effet vitrine rattachée
• Rewrite proxy entre deux projets Vercel — complexité disproportionnée

Variables d'environnement

• HPQ_DATABASE_URL — Neon en prod Vercel
• GEMINI_API_KEY — populate local ; HPQ_GEMINI_API_KEY prévu pour le cron futur

Le jeu en prod ne dépend pas de Gemini : seulement la base.

Suite de la série

Design system HP (article dédié), choix Gemini et quotas, stockage Neon et dédup, repopulation cron, validation JSON.

Quiz en prod : andrewchicout.dev.