18 octobre 2026
Vue d'ensemble
Fonctionnalités principales
7 machines en ligne, 4 séries
- MCH-001 Architecture hexagonale : 3 scénarios, 3 « et si », vue éclatée (« débrancher les adaptateurs »)
- MCH-002 Event loop JavaScript : listing de code, console « A D C B », pile bloquée, microtâches sans fin
- MCH-003 Cache-aside Redis
- MCH-004 Domain-driven design : agrégat racine, versioning, outbox
- BEN-001 RAG vs CAG vs KAG : banc d'essai avec tableau des scores
- FMD-001 Retry storm : « un clic devient 64 tentatives », graphique de charge de la base, les interrupteurs réparent
- PRT-001 Handshake TLS 1.3 : diagramme de timing
La page machine
- Scénarios guidés (lecture, pas à pas), interrupteurs « Et si… », nomenclature cliquable, journal d'événements
- Article court avec sources, glossaire et listing de code
- Mode langage simple : une phrase par étape, pièces hors sujet atténuées
- Copier le lien, télécharger la vidéo (MP4 généré dans le navigateur)
- Accessibilité : contrôle clavier (← → pour avancer, espace pour lire), reduced motion, contraste AA testé en CI, vérifié de 320 px à 1440 px
Importeur IA : « Dessine ton repo »
/import, un visiteur colle un repo GitHub public JS/TS. Environ deux minutes plus tard, il revient sous forme de machine dessinée à partir de son propre code, avec un lien partageable. Claude regroupe le code en pièces et écrit l'histoire, mais chaque route entre deux pièces doit reposer sur un import réel. Le résumé du raisonnement du modèle s'affiche en direct pendant le dessin.
Architecture
nightprint/
├── apps/
│ ├── web/ # Next.js 16, export vidéo
│ ├── importer/ # API + CLI « draw »
│ └── video/ # Remotion (vidéos X / LinkedIn)
└── packages/
├── engine/ # Schéma zod, lecteur déterministe
├── catalog/ # Les machines, en pure donnée
├── scene/ # Scène R3F, rendu WebGPU
├── blueprint/ # Relevé de repo, mise en page auto
├── ui/ # Design system (72 composants)
└── tokens/ # Design tokens, tests de contrasteLe site applique ce qu'il explique
engine) est le cœur hexagonal : il ne dépend que de zod, sans React, ni three, ni DOM. Les frontières sont imposées par les package.json et par un test d'architecture lancé à chaque pnpm check. Clin d'œil : PRJ-001 est Nightprint dessiné par son propre importeur, et ses « et si » s'appellent « Importer la scène dans le moteur » et « Importer le moteur dans le kit UI ». J'applique la même architecture en production sur l'API de Krown.
Une machine est une donnée
defineMachine() résout les 2ⁿ combinaisons d'interrupteurs dès l'import : une étape cassée fait échouer les tests et le build. Ajouter une machine, c'est un fichier et une ligne.
Le temps vit dans le moteur
player.sample() une fois par frame, sans aucun state React par frame. Ce déterminisme sert trois fois : rejouer une étape à l'identique, capturer le site image par image avec Remotion (horloge gelée par Playwright) et exporter un MP4 exact dans le navigateur (WebCodecs + mediabunny).
Pipeline de l'importeur
- Lecture du repo public à un commit fixe (≤ 3 000 fichiers, JS/TS uniquement)
- Relevé sans LLM : unités, imports (API du compilateur TypeScript), librairies, points d'entrée
- Claude produit un blueprint : pièces, zones, scénarios, « et si », article, glossaire
checkBlueprintetdefineMachinevalident ; les petites erreurs sont réparées, le reste repart au modèle (3 essais maximum)drawMachinemet en page de façon déterministe : zones, pièces, routes à angle droit
Stack technique
Frontend & 3D
- Framework : Next.js 16 (App Router, Turbopack, export statique), React 19, TypeScript 6
- 3D : three.js avec
WebGPURenderer(repli WebGL2 automatique), matériaux TSL, bloom sélectif via MRT, arêtes épaissesLineSegments2 - R3F : React Three Fiber 9, sans drei ni GLSL pour rester compatible WebGPU
- UI : Tailwind CSS 4 (palette par défaut supprimée, uniquement des tokens), IBM Plex, design system atomique
- Validation : zod 4
Vidéo
- Navigateur : WebCodecs
VideoEncoder(H.264, 1080p, 30 fps) + mediabunny pour le mux MP4 - Hors ligne : Remotion 4 + Playwright, capture image par image du site en ligne, formats 16:9 et 9:16
IA (importeur)
- Modèle : Claude Haiku via le SDK Anthropic, streaming, adaptive thinking (résumé affiché en direct), prompt caching
- Analyse statique : API du compilateur TypeScript pour extraire les imports
- Serveur : Node
httpbundlé par esbuild, file de jobs en mémoire, stockage JSON sur volume Docker
Qualité & DevOps
- Monorepo : Turborepo + pnpm (9 workspaces), Biome
- Tests : ~270 tests (Vitest + tests d'architecture
node:test) - CI/CD : GitHub Actions. Le site statique est déployé de façon atomique par SSH (clé limitée à une commande forcée), puis le job vérifie que le commit servi est le bon. L'importeur part en image Docker (GHCR) avec healthcheck et rollback automatique.
- Hébergement : VPS personnel derrière Caddy (Let's Encrypt), conteneur durci (système de fichiers en lecture seule,
cap_drop ALL, non-root, 512 Mo et 1 CPU)
Défis et enseignements
- WebGPU en production : compiler un nouveau pipeline au moment où un interrupteur bascule provoquait un freeze de 166 ms. Solution : monter à l'avance toutes les routes possibles et les faire apparaître par uniforms.
- Labels DOM au-dessus du canvas : remplacement du
<Html>de drei (9 erreurs React par page en Strict Mode) par un projecteur de labels maison. - Rendre un LLM fiable : relevé déterministe, puis modèle, puis règles avec boucle de correction, puis mise en page déterministe. L'effort du modèle a été réglé par la mesure : ~0,01 $ et 70 à 100 s en medium, contre ~0,03 $ et ~180 s en high.
- Exactitude avant tout : chaque machine est relue contre une source primaire. J'ai failli publier un contre-exemple faux : contourner un port n'inverse pas une dépendance.
- TypeScript 6 et pas 7 :
next buildvérifie les types via l'API JS de TypeScript, que TS 7 ne fournit pas. - Discipline : MVP en un week-end, puis commits atomiques qui passent tous
pnpm check.
En chiffres
- 217 commits en 7 jours
- 7 machines en ligne + importeur public
- ~32 000 lignes de TypeScript, ~270 tests
- 9 workspaces (6 packages, 3 apps), 72 composants UI
- ~1 centime de coût IA par repo dessiné
