DEV Community: Odilon HUGONNOT

SVG Diagrams and Parametric Generators: Testing 358 Questions Across 200 Seeds

Odilon HUGONNOT — Mon, 08 Jun 2026 09:00:05 +0000

"Calculate the hypotenuse BC of the right triangle at A. AB = 12 cm, AC = 9 cm, BC = ?" The student reads the question, looks at the diagram… and the diagram says AB = 3 cm. Different triangle. The values in the question are randomly generated, but the diagram is static. This kind of bug doesn't crash anything — it just makes an educational tool unusable.

Radar College is a quiz platform for French middle school exams. After building the React architecture and migrating to TypeScript, one major challenge remained: moving from static questions to parametric ones — with SVG diagrams that match the generated values. And more importantly, finding a way to test all of it without going insane.

The static question problem

The initial version had ~300 hardcoded questions. Each one: a text prompt, 4 options, a hint. It works, but after 3 attempts the student recognizes the questions. Randomization only affected the pick order and answer shuffling — not the actual numerical values.

For math and physics, this is a dealbreaker. A student who memorizes "the answer is 25 cm" hasn't learned anything. The numbers need to change on every attempt — and the distractors (wrong answers) need to be computed from the correct answer to stay plausible. No random garbage: wrong answers should correspond to typical mistakes (forgetting the square root, flipping a sign, adding instead of multiplying).

Anatomy of a generator

Each parametric question is a gen(rnd) function that receives a seeded PRNG and returns an object { q, options, correct, hint }. The PRNG is a Mulberry32: 32-bit, deterministic, fast. The same seed always produces the same question — which means we only store the seed in the history and reconstruct the exact problem for review.

// Pythagorean theorem generator — compute the hypotenuse
{ key:'pyt-1', gen: (rnd) => {
  const TRIPLETS = [[3,4,5],[5,12,13],[8,15,17],[7,24,25],[6,8,10]];
  const [a0, b0, c0] = TRIPLETS[Math.floor(rnd() * TRIPLETS.length)];
  const k = 1 + Math.floor(rnd() * 3); // multiplier 1..3
  const [a, b, c] = [a0*k, b0*k, c0*k];

  return {
    q: <>Calculate the hypotenuse BC:
       <TriangleRectangle ab={`${a} cm`} ac={`${b} cm`} bc="?" /></>,
    options: [`${c} cm`, `${a+b} cm`, `${a*a+b*b} cm`, `${Math.abs(a-b)} cm`],
    correct: 0,
    hint: `BC² = ${a}² + ${b}² = ${a*a+b*b} → BC = ${c} cm.`,
  };
}}

Three things to note. First, the pool of Pythagorean triplets guarantees the hypotenuse is an integer — no √41 ≈ 6.403 in a middle school quiz. Second, the multiplier k gives varied values without leaving integer territory. Third, the distractors aren't random: a+b (classic mistake: adding instead of Pythagoras), a²+b² (forgot the square root), |a-b| (subtraction by reflex).

An SVG kit that follows the values

The <TriangleRectangle> component above isn't decorative. It's a React component that receives values as props and renders the matching diagram — with labeled sides, a marked right angle, and a "?" on the measurement to find.

// _svg-kit.tsx — Parametric right triangle
function TriangleRectangle({ ab, ac, bc }: {
  ab?: string | number;
  ac?: string | number;
  bc?: string | number;
} = {}) {
  const lAB = ab !== undefined ? `AB = ${ab}` : 'AB';
  const lAC = ac !== undefined ? `AC = ${ac}` : 'AC';
  const lBC = bc !== undefined ? `BC = ${bc}` : 'BC (hypotenuse)';

  return (
    <svg viewBox="0 0 250 160" role="img"
         aria-label="Right triangle at A">
      <polygon points="50,30 50,130 200,130"
               fill="rgba(199,138,29,0.08)"
               stroke="currentColor" strokeWidth={1.8} />
      <rect x={50} y={118} width={12} height={12}
            stroke="currentColor" />  {/* right angle */}
      <text x={40} y={85} fill="#b45309">{lAB}</text>
      <text x={125} y={148} fill="#b45309">{lAC}</text>
      <text x={135} y={72} fill="#b45309">{lBC}</text>
    </svg>
  );
}

The same pattern applies across the kit: ConfigThales (6 props for segments AM, AB, AN, AC, MN, BC), TriangleTrigo (angle, opposite/adjacent/hypotenuse sides), GrapheAffine (slope, y-intercept). When the generator picks random values, it passes them to the SVG component — the diagram always shows the same numbers as the question.

Electrical circuits and 3D volumes

The kit goes beyond geometry. For 8th-grade physics, electricity questions need circuit diagrams. Instead of static PNG images, I built composable SVG primitives:

// Primitives: Fil, Pile, Resistance, Lampe, Amperemetre, Voltmetre
// Compositions: CircuitSerie, CircuitParallele, CircuitCourtCircuit…

function CircuitSerie() {
  return (
    <svg viewBox="0 0 240 115" role="img"
         aria-label="Series circuit">
      <Fil points={[[30,85],[30,30],[210,30],[210,85],[30,85]]} />
      <Pile cx={30} cy={58} />
      <Resistance cx={100} cy={30} label="R₁" />
      <Resistance cx={170} cy={30} label="R₂" />
      <text x={120} y={105} fill="#b45309">
        same I everywhere · U = U₁ + U₂
      </text>
    </svg>
  );
}

A <Fil> draws a polyline between points. A <Resistance> draws a rectangle with an optional label. A <Mesureur> draws a circle with a letter inside — "A" for ammeter, "V" for voltmeter. Compositions assemble these building blocks into complete circuits with annotated formulas.

For volumes (7th-grade math), same approach: Cube3D, Pave3D, Cylindre3D, Sphere3D, Cone3D components in cavalier perspective. And for geometric transformations (8th-grade math): SymetrieAxiale, SymetrieCentrale, Translation with a stylized F figure and its image. In total, 20 SVG components in a single _svg-kit.tsx file — 300 lines.

The duplicate distractor trap

When distractors are computed, there's a nasty edge case: a distractor can land on the same value as the correct answer. Example: a square with side 4, area = 16, perimeter = 16. If the distractor is "perimeter instead of area", you get 16 twice in the options.

The first instinct would be to re-roll the values. But with a seeded PRNG, you can't discard rolls — it breaks determinism. The solution: a Set of already-used values, and a systematic bump on collisions.

// Anti-duplicate pattern in every gen
const good = computeAnswer(a, b);
const used = new Set([good]);
const opts = [good];

for (const distractor of [wrongSign, wrongFormula, wrongOp]) {
  let v = distractor;
  while (used.has(v)) v += (v >= 0 ? 1 : -1);
  used.add(v);
  opts.push(v);
}

Except this pattern has its own bug. If the boundary is crossed (v <= 0 and we're decrementing), the while loop runs forever. Not theoretical: it happened on 7 generators when certain seeds produced values near zero. The fix: check the bump direction and reverse if heading out of valid space.

200 seeds per gen, in pre-commit

With 358 generators, manually checking that every value combination produces a valid quiz is impossible. I wrote a Node script (test-generators.js) that loads each quiz file through Babel, runs every gen across 200 seeds, and verifies:

4 options present
correct in [0, 3]
No duplicates in options (after stringification and French decimal formatting)
Determinism: same seed → same output (verified on 5 sentinel seeds)
Variability: at least 10 distinct outputs across 200 seeds

// test-generators.js — excerpt
function testQuestion(quizKey, domainKey, q) {
  const issues = [];
  if (typeof q.gen !== 'function') return null;
  const SEEDS = 200;
  const outputs = new Set();

  for (let i = 0; i < SEEDS; i++) {
    const seed = (i * 2654435761) >>> 0; // Knuth multiplicative
    const out = q.gen(mulberry32(seed));

    // 4 options
    if (out.options.length !== 4)
      issues.push(`seed ${seed}: ${out.options.length} options`);

    // Duplicates
    const strings = out.options.map(serializeNode);
    if (new Set(strings).size !== strings.length)
      issues.push(`seed ${seed}: duplicates → [${strings.join(' | ')}]`);

    // Variability
    outputs.add(strings.join('¤') + '|' + out.correct);
  }

  if (outputs.size < 10)
    issues.push(`low variability: ${outputs.size}/200`);

  return { quizKey, key: q.key, issues, uniqueOutputs: outputs.size };
}

The script distinguishes bugs (duplicates, correct out of range, missing options) from warnings (low variability). Only bugs fail the pre-commit. Low variability is displayed but doesn't block — some generators have a naturally narrow input space (a "true or false, is this triangle right-angled" quiz only has two possible outputs by design).

Last run result: 358/358 generators, 0 bugs, 8 variability warnings. Pre-commit passes without --no-verify.

JSX serialization, the testing surprise

The biggest technical challenge in the test script wasn't the checks — it was serialization. Quiz options aren't always strings. A fraction renders with <F n={3} d={4} />, an exponent with <sup>, a math symbol with <M>. To compare two options, you need to reduce them to text.

// Serialize a compiled ReactNode (JSX → createElement → object)
function serializeNode(n) {
  if (n == null || n === false) return '';
  if (typeof n === 'string' || typeof n === 'number') return String(n);
  if (Array.isArray(n)) return n.map(serializeNode).join('');
  if (typeof n === 'object' && n.props) {
    const children = n.props.children;
    if (children == null)
      return `<${typeof n.type === 'string' ? n.type : 'C'}/>`;
    return serializeNode(children);
  }
  return '';
}

The script doesn't mount any DOM. It shims React.createElement to return plain objects, then walks down props.children recursively. The SVG kit components are stubbed — a <TriangleRectangle ab="12 cm" /> serializes to a flat string, enough to detect duplicates without mounting a virtual DOM.

French formatting that breaks comparisons

In France, we write 3,5 — not 3.5. The app applies a Frenchification pass on options before display. Problem: the test must reproduce this exact pass, otherwise a post-formatting duplicate goes unnoticed. Example: "3.0" and "3" both become "3" after .replace(/\.0$/, '').

The script applies the same regex as app.tsx before comparing. It's an exact copy — not a reimplementation, not a port, a line-by-line copy. Any divergence between the test and the app would produce false negatives, and that's exactly the kind of bug that would go unnoticed for months.

Conclusion

The thing I didn't anticipate is that building parametric questions is a constrained combinatorics problem, not a random generation one. Randomness is the easy part. The hard part is guaranteeing that every value combination produces a valid quiz — no duplicates, no division by zero, no negative result when the context is a length, no diagram contradicting the question.

The pre-commit hook that tests 200 seeds per gen caught 13 duplicate bugs and 7 infinite loops I would never have found manually. The cost: a 180-line script and 4 extra seconds per commit. The return on investment is absurd.

Migrating to TypeScript Without a Bundler: The Radar College Story

Odilon HUGONNOT — Sun, 07 Jun 2026 09:00:03 +0000

Radar College is a quiz platform for French middle school students preparing for the "Brevet" exam. React, localStorage, SVG radar chart, gamification — the thing worked well. Until I added the 12th quiz file and started running into silent bugs. A duplicated SUBJECT.id across three files. A new Date(x) - new Date(y) returning NaN in edge cases. Props passed to components that no longer existed. Classic JavaScript, in other words.

The obvious fix: add TypeScript. Except the project has three constraints that rule out any bundler whatsoever. And that's where things get interesting.

Three constraints that change everything

Radar College isn't a "normal" project. Three decisions made at the start dictate the entire architecture:

1. Zero infrastructure. Deployment is an scp to shared PHP hosting. No Node on the server, no CI/CD pipeline, no Vercel. One index.html and two PHP files for optional sync.

2. file:// compatible. A parent must be able to hand the HTML file to their kid, double-click it, and have it work — no server, no wifi. This is a real usage constraint: not every student has reliable internet at home. Direct consequence: no history.pushState (throws SecurityError on file://), so hash routing only.

3. Editable without rebuild knowledge. The 12 quiz files (quizzes/*.tsx) must be directly editable — fix a typo in a question, add a new one — without installing Node, running a build, or understanding a pipeline. A motivated parent can do it with a text editor.

These three constraints eliminate webpack, vite, esbuild, and anything with a node_modules. A different approach was needed.

Babel Standalone: compiling TSX in the browser

The solution is Babel Standalone: a browser build of Babel. The script loads the .tsx file via a <script type="text/babel" data-presets="react,typescript"> tag, Babel compiles it to JavaScript on the fly, and React mounts it in the DOM.

The cost: ~400 KB on first load. But the Service Worker caches everything (cache-first for local assets, network-first for CDNs), so it's transparent from the second visit onwards. In file:// mode, the SW gracefully disables itself — Babel loads from CDN, the rest is in the HTML.

The real problem is that Babel Standalone has TypeScript-specific bugs that don't exist in regular Babel. Two in particular cost me time:

// ❌ Babel Standalone can't handle useState<T>(value)
const [screen, setScreen] = useState<QuizPhase>('home');
// → Parse error: the < is interpreted as JSX

// ❌ Inline casts also break
const elapsed = (new Date() as any) - startTime;

// ✅ Workaround: factory functions to type useState
const initialPhase = (): QuizPhase => 'home';
const [screen, setScreen] = useState(initialPhase);

// ✅ Workaround: intermediate variables for casts
const now: number = Date.now();
const elapsed = now - startTime;

This pattern was applied to all 10 useState calls in the main component. Not elegant, but it works and TypeScript infers the types correctly. The trade-off is acceptable: lose the idiomatic syntax, keep the type safety.

200 lines of types without import/export

Babel Standalone doesn't resolve imports. No import { Question } from './types'. All types must be globally scoped, declared as ambient in a types.ts file loaded before the application.

// types.ts — global ambient declarations (excerpts)
type Subject = 'maths' | 'physique' | 'svt';
type Level = '6eme' | '5eme' | '4eme' | '3eme';
type QuizKey = `${Subject}-${Level}`;  // template literal type
type QuizPhase = 'home' | 'quiz' | 'report';

interface Question {
    id: string;
    text: string;
    options: string[];
    correct: number;
    domain: string;
    hint?: string;
    method?: string;
}

interface DomainAnalysis {
    domain: string;
    label: string;
    total: number;
    correct: number;
    pct: number;
    status: 'acquired' | 'fragile' | 'not-acquired';
}

interface Attempt {
    date: string;
    score: number;
    weighted: number;
    total: number;
    domains: DomainAnalysis[];
    mode: 'training' | 'exam';
}

The file is ~200 lines and covers everything: data types (Question, QuizConfig, Attempt), runtime state (AnswersMap, TimingsMap, HintsMap — all Record<string, ...>), results (DomainAnalysis, AnalyzeResult), and React props for each component.

The most useful type is QuizKey: a template literal type `${Subject}-${Level}` encoding the 12 valid combinations. Impossible to pass 'maths-cm2' or 'french-3eme' without TypeScript complaining. This type alone would have prevented the duplicated SUBJECT.id bug.

A 50-line build system

The build system is a 50-line bash script with some inline Python. No webpack, no vite, no esbuild. Just marker replacement in an HTML template.

#!/bin/bash
# build.sh — inline everything into a single index.html

TEMPLATE="index.html"
OUTPUT="dist/index.html"

# 1. Read the template
cp "$TEMPLATE" "$OUTPUT"

# 2. Inline CSS
CSS=$(cat app.css)
# Python for replacement (sed struggles with multiline)
python3 -c "
import sys
content = open('$OUTPUT').read()
css = open('app.css').read()
content = content.replace('/* __APP_CSS__ */', css)
# Inline each quiz file
import glob
for f in sorted(glob.glob('quizzes/*.tsx')):
    key = f.replace('quizzes/','').replace('.tsx','')
    marker = f'/* __QUIZ_{key.upper()}__ */'
    content = content.replace(marker, open(f).read())
# Inline app.tsx
app = open('app.tsx').read()
content = content.replace('/* __APP_TSX__ */', app)
open('$OUTPUT', 'w').write(content)
"

The result: a ~300 KB index.html that contains everything — CSS, TypeScript for all 12 quizzes, application code. One file to deploy. Babel Standalone compiles it in the browser at load time. The Service Worker caches it. Done.

Is it optimal? No. Is it sufficient for an app used by a handful of students? Absolutely. And more importantly, it's understandable. Anyone can read build.sh and understand what it does. Try that with a 200-line webpack.config.js.

The IIFE and the mount race condition

Radar College's architecture is a bit unusual: routing is vanilla JavaScript in the index.html, and the React app lives in a separate app.tsx, wrapped in an IIFE for scope isolation.

The problem is that Babel Standalone compiles TSX asynchronously, but the vanilla router is synchronous. When the user lands on #/3eme/maths/quiz, the router calls window.mountQuizApp('maths-3eme') — except the function doesn't exist yet because Babel hasn't finished compiling.

// Solution: pending queue on window
// Router side (vanilla JS):
if (typeof window.mountQuizApp === 'function') {
    window.mountQuizApp(key);
} else {
    window.__pendingQuizMount = key;  // "I wanted to mount this"
}

// React side (app.tsx, after Babel compilation):
window.mountQuizApp = (key: string) => {
    setActiveQuiz(key as QuizKey);
    root.render(<App />);
};

// Check for pending mount
if (window.__pendingQuizMount) {
    window.mountQuizApp(window.__pendingQuizMount);
    delete window.__pendingQuizMount;
}

Pure plumbing for cross-world communication. In a bundled project, everything would share the same scope and this problem wouldn't exist. But the zero-build constraint forces you to make explicit things you normally take for granted.

48 E2E tests with Playwright

No unit tests. Only end-to-end tests. The choice may surprise, but it makes sense for this type of project: the value lies in user interactions (selecting an answer, viewing a score, retrieving history), not in isolated pure functions.

The 48 scenarios cover 8 areas:

What the migration revealed

The TypeScript migration was done in a single PR: 22 files, +709/-182 lines. Three review iterations, progressive score from 7.5 to 8.2/10. Here's what the types revealed in code that "worked":

Three quiz files had the same SUBJECT.id. maths-4eme, physique-4eme, and svt-4eme all declared id: 'maths'. In JavaScript, no error — quizzes loaded, questions displayed, but the dashboard mixed up results for all three 4th-grade subjects. The kind of bug a user would report as "my scores are weird" without being able to explain why.

Arithmetic on Date objects. new Date(a) - new Date(b) works in JavaScript because Date objects are implicitly converted to numbers via valueOf(). TypeScript rightfully refuses this implicit conversion: if a is undefined (unanswered question), the result is NaN, and the average time-per-question calculation becomes silently wrong.

Ghost props. Two components received props that had been renamed in the parent three weeks earlier. The code worked because the props were effectively optional (JavaScript doesn't complain when you pass extra keys to an object). But it meant the component used its default value instead of the actual one. TypeScript caught the mismatch.

Conclusion

The lesson isn't "use TypeScript" — everyone knows that already. The lesson is that a project's architectural constraints (zero-build, file://, no bundler) aren't an excuse to skip type safety. Babel Standalone + ambient declarations isn't the ideal solution, but it's a solution that works — and the bugs found during migration proved it was worth the effort.

The source code is on GitHub. All 48 tests pass. Types compile. And my nephew still doesn't know that the platform he uses every evening compiles TypeScript in his browser.

Building a Middle School Quiz App in React: Gamification, Accessibility and Adaptive Questions

Odilon HUGONNOT — Sat, 06 Jun 2026 09:00:03 +0000

My nephew has his Brevet exam in June — France's national middle school exam. He revises with paper flashcards, forgets everything in two days, and would rather watch YouTube shorts than re-read his math notes. Classic situation. I wanted to build him something motivating — not yet another revision PDF, but something that feels more like a game than homework. The result: an interactive quiz platform covering math, physics-chemistry and biology, from 6th to 9th grade.

React on the front, zero backend (localStorage), and way more work on gamification and accessibility than on the code itself.

The problem with existing quiz tools

There are dozens of Brevet revision tools online. But most share the same flaws: identical questions every time, no progress visualization, and a UX that makes you want to close the tab. A 14-year-old isn't going to stick around on a page that looks like a government form. They need instant feedback, rewards, and the feeling of making progress.

The other problem is that most quizzes treat all questions equally. A trigonometry exercise (coefficient 3 in the Brevet) weighs the same as a basic arithmetic question. A student can score 15/20 on the quiz and still bomb the exam because their gaps were concentrated in the highest-weighted domains.

30 randomized questions, weighted scoring

Each quiz picks 2 to 4 questions per domain from a bank of ~50 questions, for a total of about 30 questions per session. The student never gets the same sequence twice.

Scoring works on two axes: a raw score (all questions equal weight) and a weighted score out of 20 that reflects the actual Brevet coefficients. Equations and linear functions count 4 times more than basic arithmetic. This completely changes how students perceive their own performance — someone who nails mental calculation but struggles with trigonometry sees it immediately in the gap between their two scores.

// Domain coefficients (reflect actual Brevet weight)
const DOMAIN_WEIGHTS = {
    arithmetic:    2,
    powers:        2,
    identities:    3,
    equations:     4,
    functions:     4,
    pythagoras:    3,
    thales:        3,
    trigonometry:  3,
    geometry3d:    2,
    statistics:    2
};

// Weighted score = sum(correct × coeff) / sum(coeff) × 20
function computeWeightedScore(results) {
    let totalWeight = 0, earnedWeight = 0;
    for (const [domain, answers] of Object.entries(results)) {
        const w = DOMAIN_WEIGHTS[domain];
        totalWeight += answers.length * w;
        earnedWeight += answers.filter(a => a.correct).length * w;
    }
    return (earnedWeight / totalWeight) * 20;
}

Skills radar and progress curve

The end-of-quiz report is where I spent the most time. A simple "you got 14/20" isn't enough — the student needs to understand where they're strong and where they need to work.

The skills radar (a dynamically generated SVG) overlays the current quiz profile with the average profile from previous attempts. At a glance, you can see whether trigonometry is improving or still the weak spot. Each domain has its own detailed card: success rate, coefficient, and a toggle to review specific mistakes with hints.

The SVG progress curve plots the weighted score across recent attempts. It's simple, but seeing an upward curve has a massive psychological effect on a teenager's motivation. Far more effective than a table of scores.

// SVG radar generation — one polygon per data series
function drawRadar(ctx, domains, current, average) {
    const cx = 150, cy = 150, r = 120;
    const n = domains.length;
    const angleStep = (2 * Math.PI) / n;

    function toPoints(scores) {
        return scores.map((s, i) => {
            const angle = angleStep * i - Math.PI / 2;
            const ratio = s / 100;
            return `${cx + r * ratio * Math.cos(angle)},${cy + r * ratio * Math.sin(angle)}`;
        }).join(' ');
    }

    return `
        <svg viewBox="0 0 300 300">
            <polygon points="${toPoints(average)}" class="radar-average"/>
            <polygon points="${toPoints(current)}" class="radar-current"/>
            ${domains.map((d, i) => {
                const angle = angleStep * i - Math.PI / 2;
                return `<text x="${cx + (r+20) * Math.cos(angle)}"
                              y="${cy + (r+20) * Math.sin(angle)}">${d}</text>`;
            }).join('')}
        </svg>`;
}

Adaptive questions: targeting weak spots

This is the mechanism that makes the real difference versus a basic random quiz. Every wrong answer gets logged in a weakness tracker (localStorage). On the next quiz, frequently missed questions have 1 to 3 times higher probability of being selected.

In practice, if the student consistently misses Thales theorem questions, they'll see more of them next time — not so many that the quiz becomes repetitive, but enough for the brain to anchor the methods. It's simplified spaced repetition, without the complexity of a full Anki-style algorithm.

// Weighted selection: frequently missed questions come back more
function selectQuestions(pool, wrongTracker, count) {
    const weighted = pool.map(q => ({
        ...q,
        weight: 1 + (wrongTracker[q.id] || 0)  // base 1, +1 per past error
    }));

    const selected = [];
    while (selected.length < count && weighted.length > 0) {
        const totalWeight = weighted.reduce((sum, q) => sum + q.weight, 0);
        let random = Math.random() * totalWeight;
        const idx = weighted.findIndex(q => (random -= q.weight) <= 0);
        selected.push(weighted.splice(idx, 1)[0]);
    }
    return selected;
}

Gamification: badges, streaks and encouragement

A badge system rewards behaviors, not just results. The first completed quiz unlocks a badge. Five consecutive days unlocks another. There's a badge for trying all three subjects, one for covering all grade levels from 6th to 9th, and one for improving by more than 3 points between two attempts.

The daily streak is calculated on calendar dates — no need to do 10 quizzes per day, one is enough to keep the series going. The idea is to build a regular habit rather than marathon sessions the night before the exam. The countdown to exam day (displayed for 9th graders) adds urgency without creating stress.

An encouragement message pops up halfway through ("You're halfway there, keep going!") and a confetti animation triggers on badge unlocks. Cosmetic details, but that's exactly what makes a teenager come back the next day.

Accessibility: dyslexia mode and keyboard navigation

A toggle activates the OpenDyslexic font, increases line height and adjusts letter spacing. This isn't a gimmick — roughly 5 to 10% of students are dyslexic, and standard school assessments almost never offer this option. Accommodations exist for the actual Brevet exam (extra time, etc.), but revision tools don't account for it.

Keyboard navigation is complete: arrow keys to move between questions, keys 1 to 4 to select an answer, Enter to validate. The app also respects prefers-reduced-motion to disable animations for users who've configured it. Interactive elements are hidden from print via no-print for those who want to print their report.

Zero accounts, zero backend

Everything is stored in localStorage. No account creation, no password to remember, no server to maintain. The student types their first name and they're off. Results persist across sessions as long as the browser cache isn't cleared.

This is a deliberate choice. For a tool used by a middle schooler on the family PC, requiring email registration would be an immediate friction point. The trade-off is that data doesn't survive a browser switch or cache clear — but for a temporary revision tool (a few months before the Brevet), that's perfectly acceptable.

The only server call is an optional save.php to persist results server-side as a backup. But the quiz works perfectly without it — all computation, scoring and chart rendering happens in the browser.

Conclusion

The most interesting part of this project wasn't the React code itself — it's fairly standard state management. The real work was in the pedagogical design: which coefficients to assign, how to visualize progress without discouraging, when to encourage, how to calibrate adaptive difficulty so it stays motivating without becoming frustrating.

A revision tool that actually works is 20% code and 80% psychology. My nephew has been using it every day for two weeks. The curve is going up. We'll see in June.

Auditing a Legacy Symfony Project: Where to Start Without Doing Everything Twice

Odilon HUGONNOT — Fri, 05 Jun 2026 09:00:02 +0000

We're auditing a Symfony MessageController. The CRUD looks standard — create, update, delete, list. We start reviewing the code, noting security issues, fat controllers, missing validations. And then we open the Message entity.

The broadcast field is a string with values "Y" and "N". The type field is an int with no enum, magic numbers scattered across the controller. The title field in PHP is called titre in the database. And that's when the real question hits: are we auditing the controller, or are we auditing the entity?

If we fix the controller now, we'll write code that checks broadcast === "Y". When we fix the entity later to use a bool, we'll have to come back and touch this controller again. Same code, audited twice, modified twice. That's exactly what we want to avoid.

The three possible orders

Facing a legacy Symfony project with 15 entities, 20 controllers, a handful of services and listeners, there are three ways to organize an audit. None is universally bad — but only one avoids the systematic rework trap.

Top-down: controllers first

Start with the controllers. It's the intuitive approach — follow the HTTP flow, see what the user sees. You discover security issues, missing @IsGranted, fat controllers doing 300 lines of business logic.

The upside: it's concrete. You quickly spot which entities are underused, which services are over-engineered. The downside: every controller you audit pulls you back to the entities. You find a "Y"/"N" here, a meaningless int type there, gratuitous nullables elsewhere. You spend your time writing "fix in entity later" without ever fixing anything.

// What you find in the controller
if ($message->getBroadcast() === 'Y') {
    $this->notificationService->sendToAll($message);
}

// What you'd want to write
if ($message->isBroadcast()) {
    $this->notificationService->sendToAll($message);
}

But you can't write the second version until the entity changes. So you leave the first one. And when you do fix the entity, you'll have to come back and touch this controller.

Vertical slice: feature by feature, end to end

Pick a feature — say, message management — and audit everything at once: the Message entity, the MessageController, the MessageType form, the Twig template. Complete feature, shipped, move on to the next.

This is the approach that most resembles a real PR review. Each slice is a coherent deliverable. On a mature project with established conventions, it's excellent.

On a legacy project where conventions don't exist yet, it's a trap. Because cross-cutting rules — "all clinical entities need SoftDeleteable", "Y/N strings become bool", "every auditable entity gets Loggable + Versioned" — you discover those rules as you go. And every slice becomes a debate: "Should we add Loggable here too? Oh right, like the previous entity." Multiply by 15 entities, and it gets exhausting.

Bottom-up: entities first

Start with the data model. Go through all 15 entities, align everything: types, naming conventions, Doctrine traits (Loggable, SoftDeleteable, Timestampable), validation assertions, enums. Stabilize the foundations. Only then move up to services, listeners, controllers.

It's the least glamorous approach. No visible deliverable during the first phase. You spend time "in the dark", fixing types and adding traits to entities. Nobody notices a difference on the user side.

But when you reach the controllers, everything underneath is clean. A broadcast is a bool. A type is an enum. A title is called title everywhere. You audit control flow, security, separation of concerns — not impedance mismatches between the controller and the entity.

Why bottom-up wins on legacy

The reasoning fits in one sentence: the data model dictates everything above it. Symfony validations (@Assert) live on the entity. Form type definitions depend on entity types. Controller conditions reflect the entity's possible states. If the model is broken, everything above it is broken.

On a legacy project, entities accumulate silent technical debt. It's rarely spectacular — no visible bugs, no crashes. It's just that the status field is an int instead of an enum, that deletedAt doesn't exist because deletions are hard deletes, that half the fields are nullable for no reason.

And this debt propagates. A controller testing $status === 3 instead of $status === Status::ARCHIVED isn't a controller problem — it's an entity problem that contaminated the controller.

The migration argument

"But modifying entities means Doctrine migrations." Yes. And it's easier than you think, as long as you do it early.

If the project is in refactoring phase (not yet in production, or with a dev database you can rebuild), migrations are free. If the project is in production, migrations are necessary anyway — the question isn't "do we migrate", it's "do we migrate now in a controlled way or later in a panic when a type bug blows up in our face".

The classic top-down trap

Here's the typical scenario. You audit PatientController. You find security issues — missing @IsGranted, no check that the patient belongs to the right clinic. You fix them. Good.

Then you open the Patient entity. No SoftDeleteable — patients are hard-deleted, which is illegal in a medical context. The gender field is a free-form string instead of an enum. Birth dates are string fields formatted as "DD/MM/YYYY".

// Patient entity — before audit
#[ORM\Column(type: 'string', length: 10)]
private ?string $gender = null;

#[ORM\Column(type: 'string', length: 10)]
private ?string $birthDate = null;

// Patient entity — after audit
#[ORM\Column(type: 'string', enumType: Gender::class)]
private Gender $gender;

#[ORM\Column(type: 'date')]
private \DateTimeInterface $birthDate;

This entity change breaks the controller you just audited. The $patient->getGender() === 'M' comparisons no longer work. The date formatting in templates breaks. You have to go back.

Bottom-up avoids this scenario: by the time you reach the controller, the entity is already clean.

The two-phase method

Pure bottom-up has a flaw: if you audit entities with no idea how they're used, you risk over-engineering. Adding Loggable to a config entity that changes once a year is just noise.

The solution is a quick pre-audit. Not a full audit — an inventory.

Phase 0: entity inventory (30 minutes)

Walk through src/Entity/. For each entity, one line: what's missing, what's inconsistent, what's the business context.

Entity

Structural issues

Priority

Patient

No SoftDelete, gender string, birthDate string

High

Message

broadcast Y/N, type int without enum, title/titre mismatch

Medium

User

Missing Loggable, roles in untyped JSON

High

Config

Technical entity — fine as is

Low

Study

No Versioned, status int, gratuitous nullables

High

This inventory takes 30 minutes and changes everything. You know which entities are critical, which can wait, and most importantly — you detect cross-cutting patterns before writing a single line of code.

Phase 1: entity audit

Attack entities one by one, by priority. For each entity, the same checklist:

Types: string → enum, int → enum, string date → DateTimeInterface, "Y"/"N" → bool
Doctrine traits: Loggable + Versioned on business entities, SoftDeleteable on clinical entities, Timestampable everywhere
Nullability: a nullable field should be nullable for a business reason, not by default
Assertions: @Assert\NotBlank, @Assert\Length, @Assert\Choice — validation lives on the entity, not in the controller
Naming: consistency between PHP property name and column name

// Before: the entity accumulates silent debt
#[ORM\Entity]
class Message
{
    #[ORM\Column(type: 'string', length: 1)]
    private ?string $broadcast = 'N';

    #[ORM\Column(type: 'integer')]
    private ?int $type = null;

    #[ORM\Column(name: 'titre', type: 'string', length: 255)]
    private ?string $title = null;
}

// After: the model expresses the business domain
#[ORM\Entity]
#[Gedmo\Loggable]
#[Gedmo\SoftDeleteable(fieldName: 'deletedAt')]
class Message
{
    #[ORM\Column]
    private bool $broadcast = false;

    #[ORM\Column(type: 'string', enumType: MessageType::class)]
    private MessageType $type;

    #[ORM\Column(length: 255)]
    #[Assert\NotBlank]
    private string $title;

    #[ORM\Column(nullable: true)]
    private ?\DateTimeImmutable $deletedAt = null;
}

Phases 2, 3, 4: services → controllers → templates

Once entities are stabilized, move up layer by layer. Services and listeners first — AccessControlListener, PatientDataHistoryListener — because they depend directly on entities. Then controllers, which now work with clean types. Finally templates, with properly typed data.

At each layer, the audit focuses on that layer's real problems: security and separation of concerns for controllers, business logic for services, display and UX for templates. No more debating types — that's settled.

When vertical slice is the right choice

Bottom-up isn't always the answer. If the project already has solid conventions — clean types, Doctrine traits in place, consistent validation — then vertical slice is superior. You close out a feature end to end, ship it, move on. It's the natural workflow of a team doing PR reviews.

The question to ask: do the conventions already exist, or are we establishing them? If they exist, vertical slice. If you're discovering them as you audit, bottom-up. Establish cross-cutting rules once, cleanly, across all entities — then let the controllers conform mechanically.

Conclusion

The natural instinct on a legacy audit is to start with what's visible: the controller, the HTTP route, what the user sees. It's satisfying but it's a trap. You end up auditing facades built on foundations you're about to change.

In a legacy Symfony project, Doctrine entities are the foundations. Stabilizing them first gives you the right to audit everything else exactly once. It's less gratifying at first — nobody applauds a Loggable trait added to 10 entities — but it's the only approach where the work doesn't get redone.

The 30-minute inventory before starting is what turns an endless audit into an execution plan. You know what you'll touch, in what order, and why.

Go Generics: When to Use Them, When to Avoid Them

Odilon HUGONNOT — Wed, 03 Jun 2026 09:00:02 +0000

I had three repositories that looked identical. UserRepository, ProductRepository, OrderRepository: same structure, same FindByID, same List, same pagination logic. The only difference was the return type. Three copies of the same code. When Go 1.18 shipped with generics, I wanted to merge them all. What happened next taught me when generics are a good idea — and when they make the problem worse.

What generics actually do

Generics let you write code parameterized by types. Where before you had to either duplicate code for each type or use interface{} with runtime type assertions, you can now write a single implementation that works for multiple types — with compile-time checking.

// Before Go 1.18: duplication or interface{}
func ContainsInt(slice []int, val int) bool {
    for _, v := range slice { if v == val { return true } }
    return false
}
func ContainsString(slice []string, val string) bool {
    for _, v := range slice { if v == val { return true } }
    return false
}

// With generics: one implementation
func Contains[T comparable](slice []T, val T) bool {
    for _, v := range slice {
        if v == val {
            return true
        }
    }
    return false
}

T comparable is a constraint: T can be any type that supports ==. The compiler verifies that passed types satisfy the constraint — no runtime surprises.

Patterns where generics shine

1. Utility functions on slices and maps

This is the cleanest use case. Generic operations on collections, with no business logic:

func Filter[T any](slice []T, predicate func(T) bool) []T {
    result := make([]T, 0, len(slice))
    for _, v := range slice {
        if predicate(v) {
            result = append(result, v)
        }
    }
    return result
}

func Map[T, U any](slice []T, transform func(T) U) []U {
    result := make([]U, len(slice))
    for i, v := range slice {
        result[i] = transform(v)
    }
    return result
}

func Keys[K comparable, V any](m map[K]V) []K {
    keys := make([]K, 0, len(m))
    for k := range m {
        keys = append(keys, k)
    }
    return keys
}

At the call site, it's readable and idiomatic:

activeUsers := Filter(users, func(u User) bool { return u.Active })
emails := Map(users, func(u User) string { return u.Email })
categoryIDs := Keys(categoryMap)

2. Typed data structures

A thread-safe cache, a queue, an optional value — structures you reuse everywhere but want typed:

type Cache[K comparable, V any] struct {
    mu    sync.RWMutex
    items map[K]cacheEntry[V]
    ttl   time.Duration
}

type cacheEntry[V any] struct {
    value   V
    expires time.Time
}

func NewCache[K comparable, V any](ttl time.Duration) *Cache[K, V] {
    return &Cache[K, V]{
        items: make(map[K]cacheEntry[V]),
        ttl:   ttl,
    }
}

func (c *Cache[K, V]) Set(key K, value V) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.items[key] = cacheEntry[V]{value: value, expires: time.Now().Add(c.ttl)}
}

func (c *Cache[K, V]) Get(key K) (V, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    entry, ok := c.items[key]
    if !ok || time.Now().After(entry.expires) {
        var zero V
        return zero, false
    }
    return entry.value, true
}

Without generics, this cache returns interface{} and forces a type assertion on every call. With generics, the type is known at compile time:

userCache := NewCache[int, User](5 * time.Minute)
userCache.Set(42, User{Name: "Alice"})
user, ok := userCache.Get(42) // user is a User, not an interface{}

3. Result and Option types

A common pattern to avoid null values or implicit boolean returns:

type Optional[T any] struct {
    value   T
    present bool
}

func Some[T any](v T) Optional[T] { return Optional[T]{value: v, present: true} }
func None[T any]() Optional[T]    { return Optional[T]{} }

func (o Optional[T]) Unwrap() (T, bool) { return o.value, o.present }
func (o Optional[T]) OrDefault(def T) T {
    if o.present { return o.value }
    return def
}

When generics make everything worse

The generic repository trap

Back to my three repositories. The idea seemed good:

type Repository[T any] struct {
    db    *sql.DB
    table string
    scan  func(*sql.Rows) (T, error)
}

func (r *Repository[T]) FindByID(ctx context.Context, id int) (T, error) {
    rows, err := r.db.QueryContext(ctx, "SELECT * FROM "+r.table+" WHERE id = $1", id)
    // ...
    return r.scan(rows)
}

func (r *Repository[T]) List(ctx context.Context) ([]T, error) {
    // ...
}

In practice, it broke immediately. UserRepository needs FindByEmail. ProductRepository needs FindByCategory. OrderRepository needs FindByCustomerWithItems that does a join. The shared part — FindByID and List — represents 15% of the total code. The rest is specific. The generic factors out the 15%, complicates the 85%.

// What you end up writing anyway
type UserRepository struct {
    base *Repository[User] // the generic part
    db   *sql.DB           // for specific queries
}

// The complexity just moved somewhere else

Overly complex constraints

When generic constraints start looking like this, it's a signal:

// ❌ Too complex — use an interface instead
type Processable[T Entity, R Result, E interface{ error }] interface {
    Process(context.Context, T) (R, E)
    Validate(T) E
    Rollback(context.Context, T) E
}

// ✅ A simple interface does the same job
type Processor interface {
    Process(ctx context.Context, input any) (any, error)
}

If your generic constraint needs itself to be defined, or involves more than one type parameter with relationships between them, ordinary interfaces are almost always more readable.

When methods differ by type

Generics don't let you specialize behavior per type at runtime. If the logic differs between int and string, generics don't help — you need interfaces or two distinct functions.

The practical decision rule

Situation

Solution

Same algorithm, different types, identical logic

✅ Generics

Reusable data structure (cache, queue, optional)

✅ Generics

Behavior varies by type

✅ Interfaces

Factoring business logic that differs 85% of the time

❌ Avoid generics

Constraint with more than 2 type params

❌ Probably an interface

Need reflection or type switch

❌ Generics can't help

The key question: is the logic identical for all types, or just the structure? If it's the logic: generics. If it's the behavior: interfaces. If it's both: compose them.

Conclusion

Go generics are a measured addition to a language that already valued simplicity. They don't replace interfaces — they fill a specific blind spot: algorithms and data structures that work identically for any type.

What took me time to internalize: generics are a tool for eliminating structural code duplication, not for factoring business logic. As soon as logic starts diverging by type, you leave generics territory and enter interfaces territory — which, combined with functional options and solid DI, covers the vast majority of real-world Go architecture cases.

Dependency Injection in Go Without a Framework

Odilon HUGONNOT — Tue, 02 Jun 2026 09:00:02 +0000

The unit test took 4 seconds. Not because the logic was complex — because the service sent a real email on every call. The constructor instantiated the SMTP client internally. There was no way to replace it in tests without modifying production code.

That's the hidden dependency. It's invisible in the function signature, it doesn't crash at runtime — but it makes code impossible to test cleanly and impossible to evolve without side effects.

The hidden dependency

Here's what it looks like:

type OrderService struct {
    db *sql.DB
}

func (s *OrderService) PlaceOrder(ctx context.Context, order Order) error {
    // ... business logic ...

    // Dependency instantiated internally ❌
    mailer := &SMTPMailer{Host: "smtp.internal", Port: 587}
    return mailer.Send(order.CustomerEmail, "Your order is confirmed.")
}

To test PlaceOrder, you send an email. On every CI run, every local test, every refactor. And if you want to switch to SendGrid? You modify PlaceOrder — a function that has nothing to do with the choice of email provider.

The core principle: inject, don't create

The rule is simple: a function or struct shouldn't create its dependencies — it should receive them. That's dependency injection. Not a complicated pattern, not a framework: just passing dependencies as parameters instead of instantiating them internally.

In Go, this almost always goes through an interface, defined on the consumer side (see the article on accept interfaces, return structs):

// Interface defined in the package that needs it
type Mailer interface {
    Send(to, body string) error
}

type OrderService struct {
    db     *sql.DB
    mailer Mailer // injected ✅
}

func NewOrderService(db *sql.DB, mailer Mailer) *OrderService {
    return &OrderService{db: db, mailer: mailer}
}

func (s *OrderService) PlaceOrder(ctx context.Context, order Order) error {
    // ... business logic ...
    return s.mailer.Send(order.CustomerEmail, "Your order is confirmed.")
}

OrderService doesn't know if it's SMTP, SendGrid, or a fake. It just knows it has something that can send an email. That's decoupling.

Testing without a mock framework

You don't need testify/mock for this. An inline fake is enough in 90% of cases:

type fakeMailer struct {
    sent []string
    err  error
}

func (f *fakeMailer) Send(to, body string) error {
    f.sent = append(f.sent, to)
    return f.err
}

func TestPlaceOrder_SendsConfirmation(t *testing.T) {
    db := setupTestDB(t)
    mailer := &fakeMailer{}
    svc := NewOrderService(db, mailer)

    err := svc.PlaceOrder(context.Background(), Order{
        CustomerEmail: "alice@example.com",
        Items:         []string{"item-123"},
    })

    if err != nil {
        t.Fatalf("PlaceOrder: %v", err)
    }
    if len(mailer.sent) != 1 || mailer.sent[0] != "alice@example.com" {
        t.Errorf("expected 1 email to alice, got %v", mailer.sent)
    }
}

func TestPlaceOrder_MailerError_DoesNotSave(t *testing.T) {
    db := setupTestDB(t)
    mailer := &fakeMailer{err: errors.New("SMTP down")}
    svc := NewOrderService(db, mailer)

    err := svc.PlaceOrder(context.Background(), Order{CustomerEmail: "bob@example.com"})
    if err == nil {
        t.Fatal("expected error when mailer fails")
    }
}

The test is fast, deterministic, no network side effects. And to test the behavior when SMTP is down, set err: errors.New("SMTP down") — no mock framework needed.

Wiring in main.go

Someone has to create the concrete dependencies. That someone is main.go. It's the only place in the program that knows the concrete implementations — everything else only sees interfaces:

func main() {
    db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Fatal(err)
    }

    mailer := smtp.NewMailer(
        smtp.WithHost("smtp.internal"),
        smtp.WithPort(587),
        smtp.WithTLS(true),
    )

    orderService := orders.NewOrderService(db, mailer)
    paymentService := payments.NewPaymentService(db, stripe.NewClient(os.Getenv("STRIPE_KEY")))

    server := api.NewServer(orderService, paymentService)
    log.Fatal(server.ListenAndServe(":8080"))
}

This is the composition root. All the wiring complexity is concentrated here, not scattered across packages. Switch from SMTP to SendGrid? One line changes in main.go, not 12 files across the project.

Multiple dependencies: explicit constructor or functional options?

When a service has many dependencies, two approaches coexist in Go. If all dependencies are required and their number is fixed, the explicit constructor remains the most readable:

func NewCheckoutService(
    orders    OrderRepository,
    inventory InventoryChecker,
    payments  PaymentGateway,
    mailer    Mailer,
    logger    *slog.Logger,
) *CheckoutService {
    return &CheckoutService{
        orders: orders, inventory: inventory,
        payments: payments, mailer: mailer, logger: logger,
    }
}

If some dependencies are optional or can have default implementations, functional options fit naturally:

type CheckoutOption func(*CheckoutService)

func WithLogger(l *slog.Logger) CheckoutOption {
    return func(s *CheckoutService) { s.logger = l }
}

func WithMetrics(m MetricsRecorder) CheckoutOption {
    return func(s *CheckoutService) { s.metrics = m }
}

func NewCheckoutService(
    orders   OrderRepository,
    payments PaymentGateway,
    opts     ...CheckoutOption,
) *CheckoutService {
    s := &CheckoutService{
        orders:   orders,
        payments: payments,
        logger:   slog.Default(),
        metrics:  &noopMetrics{},
    }
    for _, o := range opts {
        o(s)
    }
    return s
}

What a DI framework won't do for you

Wire and Dig are valid tools for projects with hundreds of dependencies. But they don't solve the real problem — they automate it. If your UserService depends on 12 things, a DI framework won't tell you that those 12 dependencies might mean UserService is doing too many things.

DI frameworks generate code or use reflection. Both have a cost: reduced readability when debugging, errors caught at init time rather than compile time, and one more abstraction layer between you and what's actually happening.

In Go, for the vast majority of projects, manual wiring in main.go is simpler, more readable, and more maintainable than a framework. When manual wiring becomes painful, it's usually a design signal to address — not a signal to add a tool.

Conclusion

DI in Go isn't a complicated pattern. It's just: pass dependencies as parameters, define interfaces on the consumer side, and concentrate wiring in main.go. Three lines of principle, a few hours of practice for it to become instinctive.

What actually changes when you apply it: tests become fast and side-effect-free, refactors become local, and interfaces start revealing the real structure of the code — which responsibilities are separated, and which are still tangled together.

In the last article of this series, we push reusability one step further with Go generics — for the cases where neither interfaces nor functional options are enough.

Functional Options in Go: Escaping the 9-Parameter Constructor

Odilon HUGONNOT — Mon, 01 Jun 2026 09:00:03 +0000

Sprint 1: NewHTTPClient(host string, timeout time.Duration). Clean, readable, nothing to complain about. Sprint 3: add an auth token and a user-agent. Sprint 5: retry count, max connections, custom TLS. By sprint 8, the constructor looks like this:

client := NewHTTPClient(
    "https://api.example.com",
    10*time.Second,
    3,
    "Bearer eyJhbGci...",
    "MyApp/2.1",
    100,
    true,
)

What's the 4th parameter again — the token or the user-agent? And what does that final true enable? Strict TLS? Logging? Exponential backoff? You can't read this without checking the signature. You can't maintain it without making a mistake.

That's the problem functional options solve. It's not magic — it's an idiomatic Go convention popularized by Rob Pike, used throughout the standard library and major open-source projects.

The naive fix: a config struct

The first instinct is to group parameters into a struct:

type HTTPClientConfig struct {
    BaseURL   string
    Timeout   time.Duration
    Retries   int
    AuthToken string
    UserAgent string
    MaxConns  int
    TLSStrict bool
}

func NewHTTPClient(cfg HTTPClientConfig) *HTTPClient {
    // ...
}

Better at the call site. But it has two problems. First, every caller must supply all fields — there's no clean way to express "use the default" without external documentation. Second, you end up with cfg.Timeout = 0 that could mean "no timeout" or "I forgot", and you can't tell which.

The functional options pattern

The idea: instead of passing a config struct, pass functions that modify the internal struct. Each option is a standalone, explicitly named function.

type HTTPClient struct {
    baseURL   string
    timeout   time.Duration
    retries   int
    authToken string
    userAgent string
    maxConns  int
}

// Option is a function that configures an HTTPClient.
type Option func(*HTTPClient)

func WithTimeout(d time.Duration) Option {
    return func(c *HTTPClient) {
        c.timeout = d
    }
}

func WithRetries(n int) Option {
    return func(c *HTTPClient) {
        c.retries = n
    }
}

func WithAuth(token string) Option {
    return func(c *HTTPClient) {
        c.authToken = token
    }
}

func WithUserAgent(ua string) Option {
    return func(c *HTTPClient) {
        c.userAgent = ua
    }
}

func WithMaxConns(n int) Option {
    return func(c *HTTPClient) {
        c.maxConns = n
    }
}

The constructor sets sensible defaults, then applies each option in order:

func NewHTTPClient(baseURL string, opts ...Option) *HTTPClient {
    c := &HTTPClient{
        baseURL:   baseURL,
        timeout:   30 * time.Second, // sensible default
        retries:   3,
        userAgent: "Go-HTTP-Client/1.0",
        maxConns:  100,
    }
    for _, opt := range opts {
        opt(c)
    }
    return c
}

At the call site, every parameter is explicitly named. You only pass what you want to change:

// Minimal — defaults are fine
client := NewHTTPClient("https://api.example.com")

// Explicit overrides
client := NewHTTPClient("https://api.example.com",
    WithTimeout(10*time.Second),
    WithAuth("Bearer eyJhbGci..."),
    WithRetries(5),
)

No more guessing. Order doesn't matter. Adding a new option never breaks existing callers — those who don't need it simply don't use it.

Defaults and validation

Defaults live in the constructor, not scattered across callers. That's the natural place to centralize and document them. Validation happens after options are applied:

func NewHTTPClient(baseURL string, opts ...Option) (*HTTPClient, error) {
    if baseURL == "" {
        return nil, errors.New("baseURL required")
    }

    c := &HTTPClient{
        baseURL:  baseURL,
        timeout:  30 * time.Second,
        retries:  3,
        maxConns: 100,
    }

    for _, opt := range opts {
        opt(c)
    }

    // Validate after options are applied
    if c.timeout <= 0 {
        return nil, errors.New("timeout must be positive")
    }
    if c.maxConns < 1 {
        return nil, errors.New("maxConns must be >= 1")
    }

    return c, nil
}

The order matters: validate after applying options, not before. Otherwise an option that sets timeout to zero followed by one that sets it to 5 seconds would be wrongly rejected.

Composing options

An option is just a function. You can compose them freely — useful for pre-configured profiles:

// Profile for internal calls (fast-fail)
func WithInternalDefaults() Option {
    return func(c *HTTPClient) {
        c.timeout  = 2 * time.Second
        c.retries  = 1
        c.maxConns = 500
    }
}

// Profile for third-party APIs (patient)
func WithExternalDefaults() Option {
    return func(c *HTTPClient) {
        c.timeout  = 15 * time.Second
        c.retries  = 5
        c.maxConns = 20
    }
}

You can also write a helper that bundles multiple options into one:

func WithOptions(opts ...Option) Option {
    return func(c *HTTPClient) {
        for _, o := range opts {
            o(c)
        }
    }
}

// Composed profile for Stripe in production
func WithProductionStripe() Option {
    return WithOptions(
        WithExternalDefaults(),
        WithUserAgent("MyApp/2.1"),
        WithAuth(os.Getenv("STRIPE_TOKEN")),
    )
}

When to skip it

The pattern is powerful but not universal. Three cases where something else is better:

The constructor has one or two parameters. NewCache(ttl time.Duration) doesn't need to become NewCache(WithTTL(5*time.Minute)). That's added complexity with no payoff.

Config needs to be serialized/deserialized. If you load config from YAML files or environment variables, a flat struct with JSON tags is simpler. Functional options don't marshal.

Options are strongly interdependent. If enabling option A without option B makes no sense, the free-composition model becomes a trap. In that case, dedicated constructors per mode are clearer: NewHTTPClientWithTLS(...), NewHTTPClientWithProxy(...).

Conclusion

Functional options aren't a style trick — they solve a real API design problem. A constructor that keeps growing is a signal that its parameters have different weights: some are required, some have sensible defaults, some are rarely needed. Functional options let you express exactly that.

The real gain isn't call-site readability — it's that each option is a testable, named unit. You can pass WithTimeout(t) in a test with t = 100*time.Millisecond without changing the constructor's signature. That's the lasting benefit.

In the next article in this series, we'll see how to combine these options with Go interfaces in a dependency injection pattern without a framework — where functional options and Go interfaces work together.

Claude Code: I Had 10 Plugins Active at Once — Here's What It Actually Costs

Odilon HUGONNOT — Sun, 31 May 2026 09:00:04 +0000

One morning, Claude Code refused to start. Credits exhausted. I had a €200 plan, an automated monitoring system running continuously, and Claude Code as my pair-programming tool for everything else. Nothing unusual on the surface — but the credits were running out twice as fast as expected, and I couldn't figure out why.

The monitoring system, sure. The CLI called in a loop every 12 hours is easy to calculate. But the interactive sessions seemed reasonable. When I dug deeper, I found the real culprit: ten Claude Code plugins active simultaneously, half of which I never actually used.

What I Had Installed

Over the weeks, I had enabled plugins as needs arose: superpowers for structured skills, context7 for library docs, playwright for scraping, code-review, frontend-design. Plus a few others. The logic: have the tool ready in case the need arises.

That's the reasoning mistake. I treated plugins like browser extensions — sitting in the background, inert until clicked. Claude Code plugins don't work that way.

What Plugins Actually Do

Every active plugin injects content into the system prompt on every exchange. Not on demand. Not only when you invoke them. On every message, in every session.

The superpowers plugin, for instance, lists all available skills in every system reminder. context7 injects its usage instructions. playwright does the same. Multiply that by ten plugins, and every conversation turn starts with a context bloated by several thousand tokens — before you've typed anything.

The formula is straightforward: injected token = billed token, even if it belongs to a plugin you haven't used in two weeks.

The Concrete Math

With Sonnet 4.6, input tokens cost $3 per million. An average-sized plugin injects roughly 2,000 tokens of context per message. Ten plugins: 20,000 extra input tokens per exchange.

Over an active session with 50 exchanges, that's 1 million extra input tokens — $3 — solely from passive plugins. Across a day with several sessions, it adds up fast.

On its own, that's not catastrophic. But combined with an automated monitoring system already making dozens of API calls per day, both effects compound and drain the budget far faster than actual usage would suggest.

How to Diagnose Your Situation

Token consumption isn't directly visible in Claude Code, but you can infer what your plugins are injecting. In ~/.claude/settings.json, the enabledPlugins key lists what's active:


{
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true,
    "context7@claude-plugins-official": true,
    "playwright@claude-plugins-official": true,
    "code-review@claude-plugins-official": true,
    "frontend-design@claude-plugins-official": true
  }
}

For each plugin set to true, ask yourself: "Do I actually use this plugin in at least half of my sessions?" If not, disable it. You can re-enable it in 30 seconds via /plugin when the need arises.

The Right Usage Strategy

The rule I follow now: no plugins active by default, enable on demand. Plugins aren't permanent features — they're subscriptions to context. Every active plugin is a fixed cost on every single message.

For recurring workflows like article creation or debugging, skills embedded in CLAUDE.md files or local skills (~/.claude/skills/) are a better alternative: they only inject when you explicitly invoke them.

The same logic applies to CLAUDE.md files themselves: every line loaded on every session is a billed token. An 8KB CLAUDE.md documenting the entire project architecture costs more than a minimal one that points to reference files. Better to have several specialized CLAUDE.md files and let Claude read the code than to pre-digest everything into context.

Conclusion

The surprise isn't that plugins cost tokens — it's that nothing in the interface makes it visible. You enable a plugin, forget about it, and it keeps weighing on every exchange in silence.

If your credits are disappearing faster than expected, before optimizing prompts or switching models, start by listing what's active in settings.json. The answer is usually right there.

AI + TMDB: 3 Passes to Match Torrent Posters — Prompt Iteration With Real Numbers

Odilon HUGONNOT — Sat, 30 May 2026 09:00:04 +0000

ShareBox displays shared folders as a Netflix-style grid with TMDB posters. The problem: folder names come from torrents. Naruto.INTEGRALE.MULTI.VFF.1080p.BluRay.x264-AMB3R needs to match "Naruto" on TMDB — not "Naruto Shippuden", not "Naruto the Movie". And Vol 1 must definitely not match "Kill Bill: Volume 1".

Basic regex + TMDB search works for 80% of cases. For the remaining 20%, I built a 3-pass AI pipeline (Claude Haiku via CLI) with a cron every 30 minutes. Here's each pass in detail, the exact prompts, and iterations measured on 290 real entries.

The pipeline: regex first, AI as safety net

The architecture is layered, cheapest to most expensive:

Regex + TMDB (inline, every browse): extract_title_year() cleans the name, searches TMDB, takes the first result with a poster. Free, instant, correct ~80% of the time.
Pass 1: AI extraction (cron --pending): for names where regex failed, send the raw name to Claude Haiku to extract a clean title, then re-search TMDB.
Pass 2: AI verification (cron --verify): send {name, matched TMDB title} pairs to AI to detect false positives. If false → suggest a better title.
Pass 3: candidate selection (when pass 2 detects a false positive): search TMDB with the suggested title, get 15 candidates, send the list to AI to pick the right one.

Pass 1: title extraction — the prompt that skips too much

The first prompt was simple: "extract the proper movie title for a TMDB search." Tested on 290 real names, it produced 72 false skips — the AI considered "Naruto.INTEGRALE", "Pokemon La Series", "Despicable Me COLLECTION" as non-titles and marked them skip=true.

The fix: explicit rules about what to keep vs. skip, a "when in doubt, skip=false" rule, and instructions to translate known English titles to French. Result: 72 → 41 skips. 31 improvements, zero regressions.

Pass 2: verification — 46 false negatives on seasons

The verification prompt sent {name, TMDB title} pairs and asked correct: true/false. On 247 entries, it flagged 55 as incorrect. But 46 were false negatives.

The AI didn't know that S01 → "Season 1" is a correct match — it's a TMDB season poster, not a generic match. Same for all 34 Simpsons seasons, 11 Walking Dead seasons, 4 Batman seasons.

The fix: a "Special cases — do NOT mark as incorrect" section explaining that season folders matched to season titles are correct, and translations/saga names are fine. Result: 55 → 9 incorrects. All 9 are real problems. Zero false negatives.

Pass 3: the pick that solves the TMDB problem

When pass 2 detects a false positive and suggests "Naruto" as a better title, we search TMDB. Problem: TMDB returns results by popularity. "Naruto" → Naruto Shippuden (more popular). Taking the first result reproduces the error.

The solution: get 15 TMDB candidates (via multi + tv + movie endpoints), send the full list to AI with the filename for context. The AI picks {"idx": 1} — Naruto (2002), the original series. The word "INTEGRALE" in the filename helps it understand this is the complete series, not a spin-off.

A gotcha: Claude sometimes adds explanations after the JSON, breaking parsing. Fix: extract {"idx": N} via regex instead of full JSON parsing.

Final numbers

Prompt

Before

After

Improvement

Pass 1 (extraction)

72 false skips

-43%

Pass 2 (verification)

55 false negatives

9 (all real)

-84%

Pass 3 (candidate pick)

4 parse failures

-100%

What I learned

Measure before iterating. Without 290 real entries as a benchmark, I would have iterated blindly. The numbers showed pass 2 v1 had 84% false negatives — impossible to see without real data.

Edge cases dominate. 46 out of 55 false negatives came from one pattern: season folders. One line in the prompt ("seasons matched to Season N are CORRECT") eliminated 84% of errors. The 80/20 rule applies to prompts too.

Parsing matters as much as the prompt. A perfect prompt is useless if parsing breaks. The AI adds text, code fences, explanations. Regex extraction is more reliable than json_decode().

Layered architecture reduces costs. Free regex handles 80%. AI only runs on the remaining 20%. Pass 3 (the most expensive) only fires when pass 2 detects a problem — 9 times out of 290 entries.

The best prompt isn't the one with the most instructions — it's the one that precisely describes edge cases. "When in doubt, skip=false" and "seasons are CORRECT" are worth more than 20 lines of generic rules.

I Audited My Own Open-Source Project With 26 AI Agents (and Found a Real Vulnerability)

Odilon HUGONNOT — Fri, 29 May 2026 15:25:10 +0000

ShareBox is my self-hosted streaming server: a PHP thing I built because I just wanted to send someone a link to a movie without installing Plex and its ten gigabytes of dependencies. It runs on my seedbox, serves my users, and one morning I notice it's starting to pick up a few stars on GitHub.

And then, that little voice: "does this thing actually hold up?" Because between "works on my machine" and "code that strangers are going to install on their own box," there's a chasm. A chasm full of flaws I can't see anymore, because I've had my nose in it for weeks.

Normally, you re-read your code. Except re-reading 22,000 lines alone, honestly, you do it badly: you skim over what you think you already know. So I tried something else — unleashing a pack of 26 AI agents on it, each with a precise mission, and seeing what surfaced. Spoiler: they found a flaw that had been sitting right under my eyes from the start.

26 agents to comb through my own code

The idea wasn't "AI, tell me if my code is good" — that always produces the same encouraging, useless mush. The idea was to orchestrate: split the audit into roles, run the agents in parallel, then have a final, deliberately harsh agent tear apart the conclusions.

The pipeline looked like this: eleven readers start in parallel, each swallowing an entire slice of the code (the core, the streaming handlers, the API, the front end, the tests, the Docker setup…). Their reports flow up into an architecture synthesis and a test-coverage analysis. Then twelve "radar" agents each score one single axis — security, performance, architecture, tests… And finally, a "verdict" agent re-reads every score in adversarial mode: its job is to knock down the ones that are too kind.

Audit pipeline: 11 readers in parallel, then synthesis, then 12 radar agents, then an adversarial verdict. 11 readers in parallel each slice of the code read in full Architecture + coverage synthesis connect the pieces, measure the gaps 12 radar agents one agent = one scored axis Adversarial verdict knocks down kind scores → final score + roadmap

The pipeline: read in parallel, connect, score axis by axis, then have it all torn apart by a deliberately harsh final agent.

The verdict came in: 5.04 out of 10. Deliberately harsh calibration — the final agent was told to score like a demanding staff engineer, keeping in mind that "a few-weeks-old PHP media server is not Jellyfin." It stings in the moment. But a low, well-argued score is worth a thousand complacent "great project!"s.

The flaw that was right under my eyes

The moment that justifies the whole exercise on its own: one of the security agents flags the Docker startup script. My entrypoint.sh generates config.php from environment variables. And right above it sat a comment, in my own hand: "Sanitize strings to prevent PHP injection."

Except the sanitization only covered strings. Three numeric/boolean variables were interpolated raw into the generated PHP file:

define('STREAM_MAX_CONCURRENT', ${MAX_CONCURRENT});

Translation: if someone deploys the container with an environment variable like:

SHAREBOX_STREAM_MAX_CONCURRENT='1);system($_GET[x]);//'

…then the generated config.php contains executable PHP. Arbitrary code execution, in the config file, right under a comment that claimed to prevent it. The kind of thing you stop seeing because you wrote it yourself and you trust it.

Warning — always verify the agents. Before taking the agent's word for it, I went and re-read the source myself. That's the golden rule: an agent that says "vulnerability confirmed" can be wrong, and so can one that says "all good." Here the flaw was real. The fix: validate that these variables really are integers (or true|false) before writing them, otherwise fall back to a safe value.

Along the way, the audit also flagged write endpoints (TMDB poster management) reachable by anyone holding a public link, an unbounded ZIP export that could monopolize the server, and a database backup triggered on every web request. Seven "quick win" fixes in total — each verified in a real Docker container with an end-to-end test suite before touching production.

When my own fix introduced a bug

Here's the most instructive moment, and the most humbling. After applying my seven fixes, I ran another agent cycle — this time to re-score and hunt for regressions. And one of them found a bug. In my fix.

By moving the database backup out of the web request (good idea), I'd wired it onto container startup. But that code runs as root, and SQLite in WAL mode creates side files (-wal, -shm). The result: on restart over an already-populated volume, those files were owned by root, and the web server (running as www-data) could no longer write to the database. A fix that works on first launch and breaks on the second. The worst kind of bug.

No rushed human re-runs a full audit right after "finishing." That's exactly where the agent pack wins: it doesn't get tired, it doesn't congratulate itself, it re-reads the diff with the same cold rigor the second time as the first. Bug fixed, re-tested on restart, and this time for real.

Tests that read the code vs. tests that run it

The other slap from the audit landed on my tests. I had hundreds of them, I was proud of my little green badge. Except an agent put its finger on a comfortable lie: a large chunk of those tests read the source code and checked that a string was present in it — instead of running the code and checking its behavior.

// What the test did (reading the source):
$source = file_get_contents('functions.php');
$this->assertStringContainsString('aresample=async=1', $source);

// What a real test does (execution):
$args = buildFilterGraph(720, 0, burnSub: 2);
$this->assertStringContainsString('overlay', $args); // the filter is ACTUALLY built

The difference is huge. The first test stays green even if the function is broken, as long as the string is lying around somewhere in the file. It's fake coverage. The code that actually serves a file's bytes (HTTP Range handling, the heart of a streaming server) was never executed in a test.

So I converted the critical paths into real execution tests: an ephemeral PHP server that serves a file and checks the 206 Partial Content responses byte by byte, real calls to the ffmpeg command builders, the security gate tested over real HTTP. The "E2E coverage" axis went from 3 to 5 on the radar — the biggest jump of the whole exercise, and the most deserved.

The audit's best advice: don't follow it all the way

By the end, the score had climbed from 5.04 to 5.72. And the natural urge is to keep climbing. The verdict clearly pointed at the ceiling: two monolithic files of ~2,300 lines each, mixing routing, auth, business logic and views. The "textbook" answer: split it all up, introduce a router, controllers, namespaces.

And there, the final agent did something I didn't expect from an audit: it advised me not to.

A good audit also tells you what NOT to do. Rewriting 4,700 lines of procedural code that works, whose core (the ffmpeg pipeline) isn't even covered by execution tests, for a solo open-source project: weeks of work, a huge regression risk, and zero added value for the user. The risk/value ratio is bad. Keeping a deliberate procedural architecture is a defensible choice.

Instead, the highest-leverage move was invisible and risk-free: extend static analysis (PHPStan) to those never-analyzed big files, freezing the existing debt in a baseline. Result: ~4,700 of the riskiest lines are now under a net — any new regression fails CI, without forcing me to clean everything up today. Five minutes of config beat three weeks of rewrite.

What to take away

The agent pack didn't "audit in my place." It did what a lone human does badly: actually read every line, no skimming, no author's blind spot, in parallel, and start over after the fixes without getting bored. It found a real vulnerability, exposed fake test coverage, and even caught a bug in my own fix.

But at no point did it decide for me. I'm the one who verified the flaw in the source before believing it. I'm the one who decided one fix deserved a deploy and another deserved to wait. And it was the adversarial agent, not the complacent one, that produced the real value — by scoring harshly, and by saying "stop, don't overdo it."

The real win isn't the rising score. It's knowing, with numbers to back it, where the debt is, which part is worth repaying, and — the hardest thing for a developer — which part you should accept and leave alone.

Adapting Your Claude Code Workflow by Subscription: Pro, Max $100, Max $200

Odilon HUGONNOT — Fri, 29 May 2026 09:00:04 +0000

The question comes up often: do you really use Claude differently depending on your subscription? On Max $200, should you use Opus at maximum effort all the time, or is there a smarter way to work?

Short answer: yes, the workflow changes. Not just because of the model — because of budget psychology. When you know you can burn through your daily limit in 30 minutes, you code differently. And when the limit disappears, other things become important instead.

What the three subscriptions actually give you

Before talking workflow, the raw facts. Anthropic talks about "5x usage" for Pro, "20x" for Max $100, "60x" for Max $200. In practice with Claude Code:

Pro ($20)

Max ($100)

Max ($200)

Default model

Sonnet

Sonnet or Opus

Opus

Long sessions

Avoid

No constraint

/clear between tasks

Required

Recommended

For speed

Optimised CLAUDE.md

Critical

Useful

Useful (speed)

Parallel agents

Conserve

Generously

Full audits / reviews

Rare

Regular

At will

Pro ($20) — working with constraints, not against them

On Pro, Opus is available but rationed. You get it a few times per day, and an intense session can exhaust it. Sonnet is the everyday model.

The natural reflex is to "save Opus for real questions." That's partially right, but badly applied it becomes paralysing — you spend time deciding whether the question deserves Opus instead of actually working. The useful rule is simpler: Sonnet by default, Opus only when the question involves an irreversible decision or a bug you can't diagnose after two attempts.

What genuinely changes the value/token ratio on Pro:

/clear between tasks, not end of day. A session that accumulates context across 3 different topics costs 3x more than 3 clean sessions. The discipline here is real — you need to stop, clear, restart. It goes against the feeling of "momentum" but the difference on the day's limit is significant.

Broad questions are expensive for little return. "How can I improve this file?" triggers a complete analysis. "The buildPayload() function on line 47 — does it handle the null case?" costs 10x less and gives a more useful answer. Precision isn't just courtesy — it's economics.

Short CLAUDE.md, complete .claudeignore. Every line of CLAUDE.md is loaded every session. A 300-line file versus a 25-line file, multiplied across all sessions in a day, represents a non-negligible fraction of your budget. The token optimisation covered in this article isn't optional on Pro.

Max ($100) — the middle ground that enables real sessions

The jump from Pro to Max $100 is bigger than it looks. It's not just "more tokens" — it's the disappearance of defensive planning. You stop asking yourself whether you can afford this question.

Opus is accessible for serious work sessions. Sonnet stays relevant for mechanical tasks: generating a commit message, making a quick fix, answering a documentation question. The switch doesn't have to be conscious every time — Sonnet by default, Opus when you know you're tackling something complex.

What Max $100 unlocks concretely:

Full reviews and audits. On Pro, asking for a complete review of a 500-line module is a luxury. On Max $100, it's a regular practice. The quality of code on an active project reflects this directly.

Long refactoring sessions. A refactor touching 5 files with cross-dependencies requires Claude to hold the full context. On Pro, you fragment and lose coherence. On Max $100, you can run the session in full.

Parallel agents without guilt. Launching two agents in parallel to explore two approaches is reasonable on Max $100. On Pro, it doubles your usage in one shot.

Max ($200) — when the constraint disappears, what remains

Permanent Opus, no counting. The question becomes: do you really need to run everything at maximum effort?

No. Not for budget reasons, but for speed and clarity reasons. A context loaded with 200 files and a 2-hour conversation gives slower and sometimes less precise answers than a clean session focused on one problem. The discipline of /clear stays useful — not to save tokens, but because a short context remains better than an overloaded one.

What Max $200 changes in practice:

Systematic audits. Before starting a feature, have Claude read the entire relevant module to understand existing patterns. On lower subscriptions, that's an investment you ration. On Max $200, it's the natural starting point.

Generous parallel agents. Launching 3 or 4 agents on independent tasks simultaneously — exploring approaches, generating tests, writing documentation — without watching the counter. The real time savings on complex projects is substantial.

Extended research mode. Two-hour sessions on an architecture problem, with multiple back-and-forths, multiple code reads, multiple tested proposals. The kind of work you avoid on Pro because it's too expensive, but that produces the best decisions.

What stays useful regardless of subscription

Two things don't change with budget:

Question precision. "Look at the whole codebase and tell me how to improve the architecture" is a bad question on any subscription. Not because it's expensive, but because it produces a vague answer. Precision is a communication skill, not an economics skill.

Short CLAUDE.md. On Pro, it saves budget. On Max $200, it saves speed — less useless context loaded each session, faster responses, less noise in the instructions. A 25-line targeted CLAUDE.md remains better than a 200-line exhaustive one, regardless of what the subscription allows.

Conclusion

The real determinant of workflow isn't the model — it's the presence or absence of the budget constraint. On Pro, it structures everything: questions, session length, which tasks to delegate. On Max $200, it disappears and other priorities emerge — speed, precision, context quality.

What doesn't change: the basic good practices. Short CLAUDE.md, precise questions, /clear between distinct contexts. These habits aren't economy hacks — they produce better interactions regardless of budget. They apply on Pro out of necessity, on Max by choice. The result is the same.

Building a Side Project with AI Pair Programming: Lessons Learned with Sharebox

Odilon HUGONNOT — Thu, 28 May 2026 09:00:02 +0000

Sharebox started from a simple frustration: Plex and Jellyfin are overkill when you just want to send someone a movie link. The project took shape over a few intense days of work, with an AI as a permanent pair. Not vibe coding, not blind delegation — something in between, and quite different from both.

What I learned about this way of working doesn't match what you usually read. Not the naive enthusiasm ("AI codes for you"), not the posture scepticism ("it's worthless"). It's more nuanced, and very visible in the git history.

A project, not a prompt

The stack choice was deliberate and contrarian: pure PHP 8.1, SQLite in WAL mode, zero external dependencies. No framework, no composer at the start. The AI pushed for Laravel several times. I said no.

That's where real pair programming begins. The AI optimises for what it's seen most in training data: Laravel projects, ORMs, abstraction layers. It's right 80% of the time. For a self-hosted file sharing tool where the main constraint is "no system requirements except PHP and SQLite", it's wrong.

The result: a SQLite database created automatically on first launch, a config file auto-generated from environment variables, Docker-ready without it being the only deployment option. The AI contributed to implementing these choices once they were set — but the choices themselves, I made those.

AI pair programming only works if you know where you're going. The AI is an excellent executor and a decent devil's advocate. It's not an architect.

What it concretely changes

Three real problems where the AI pair genuinely accelerated things.

The three streaming modes

Sharebox streams video. The problem: an H.264/AAC file in an MKV container can't be streamed directly in a browser. An H.265 file can't be played on iOS. A file with image-based subtitles (PGS) can't be displayed natively.

The solution: three modes. Native for files that work as-is (MP4/H.264, zero CPU). Remux for container changes without re-encoding (MKV → MP4, minimal CPU). Transcode for everything else (ffmpeg, high CPU).

The AI produced the codec detection code via ffprobe quickly. What would have taken a day of documentation reading took two hours. The decision logic between the three modes — I wrote that, after challenging every AI proposal that mixed up the cases.

File-locking for FPM workers

PHP-FPM creates parallel workers. When a browser opens two tabs or an iOS player makes parallel range requests, multiple workers can simultaneously start the same ffmpeg process. The result: 800% CPU, corrupted output files.

I described the problem. The AI proposed a Redis mutex. I said no — Redis is a dependency, we stay dependency-free. It proposed a file lock. We implemented it together: a .lock file per segment, flock() with LOCK_EX | LOCK_NB, timeout if the lock isn't acquired within 30 seconds.

The pair worked here because concurrency problems are exactly where AI excels — it's a known, documented pattern with proven solutions. My role was to constrain the solution to the project's rules.

Subtitle caching

Extracting subtitles from an MKV with ffmpeg takes 15–20 seconds for a 2-hour file. Unacceptable at play time. The solution: background extraction on first access, disk cache afterwards.

The AI wrote the cache mechanism. Then we discovered a bug: the browser was caching the empty HTTP response (during extraction), and subsequent requests returned empty even after extraction completed. The AI proposed Cache-Control: no-cache headers. Correct. The final gain: 20 seconds of latency eliminated on subsequent plays.

The limits nobody talks about

AI pair programming has blind spots. Not the obvious bugs — the AI often fixes those faster than I do. The structural blind spots.

Project context doesn't persist. Every session, the AI starts from scratch. It doesn't know you decided not to add an authentication system. It doesn't know deployment must fit on a €3 VPS. It will propose JWTs, refresh tokens, Redis for sessions. You have to re-explain constraints every time — or use a well-maintained CLAUDE.md.

It doesn't maintain scope discipline. This is the most insidious problem. "We could also add..." is a phrase the AI uses often. A notification system. A full REST API. A playlist system. Each suggestion is reasonable in isolation. Together, they turn a simple tool into a complexity monster. Saying no regularly is a skill in itself in this way of working.

It agrees too easily. If you propose a flawed approach, it'll implement it cleanly. A human pair would have said "wait, are you sure?" The AI by default says "here's the implementation." You have to explicitly ask it to challenge your choices.

The pattern that works

After several sessions on sharebox, the pattern that produces the best results is this:

Pair review, not delegation. "Write me the streaming function" gives something that works but doesn't respect the project's constraints. "Here's my implementation, what's problematic?" gives something useful.

Describe the problem, not the solution. "I have a concurrency problem on FPM workers when multiple requests arrive simultaneously" is far better than "implement a mutex." The second formulation gives a generic answer. The first triggers real thinking about the context.

Never accept the first solution. Not because it's bad — it's often correct. But because there's almost always a constraint the AI hasn't accounted for. Asking "what are the alternatives?" and "what are the limits of this approach?" systematically reveals something useful.

Keep control of git. Every commit is a decision. The AI doesn't commit — you do. This minimal friction is healthy: it forces you to read what's going into the repo rather than merging blindly.

What the git log reveals

Sharebox's recent commit history shows something interesting: the latest commits are almost all corrections and hardening, not features.

Sanitising filenames in Content-Disposition to prevent injection. Fixing an iOS hoisting bug where browser detection was called before initialisation. Fixing a subtitle cache poisoning caused by browser caching. Fixing a duplicate ffmpeg process spawned from parallel requests.

That's the reality of AI pair programming on a project built over a few days: the iteration speed is real. You reach a first working state quickly. Then the consolidation work begins — and there, the AI is less useful than during the build phase. Timing bugs, race conditions, browser edge cases: the AI proposes solutions, but diagnosing the actual problem often requires careful log reading that the AI can't do for you.

The refactoring is visible too: over 1000 lines of JS/CSS extracted into separate files. That cleanup, I wanted it. The AI executed it well, but it didn't need it — it would have kept adding code to the same file without complaint.

Conclusion

Sharebox works. It runs on a NAS, serves movies, handles subtitles, survives parallel requests. It took a fraction of the time it would have taken alone.

What AI pair programming changed is iteration speed on known problems. Video streaming, concurrency handling, codec detection: documented domains where AI is operational fast. What it didn't change: scope decisions, architecture, the discipline not to over-engineer. Those decisions remain human, and they have direct impact on the quality of the result.

The real gain isn't "AI codes for me." It's "I have a pair available 24/7 who knows most patterns, doesn't get tired, and can implement what I validate." That's different. And it's already a lot.