Reading
Helper

Content is data. One screen plays a lesson.

There is no Swift file for “the /m/ lesson” or “the rhyming lesson.” Lessons, activities, and skills are JSON, and the app contains one generic lesson player plus one renderer per activity primitive — listen and choose, sound basket, read and reveal, and seven others. Wanting custom behaviour for one specific lesson is a signal that a new primitive is needed, not an excuse to special-case a screen. Ten primitives currently cover a twelve-lesson curriculum without a single bespoke view, so new lessons are content commits rather than code changes.

The validator is the actual author of quality here

One content-engine package owns every rule — schema shape, dangling references, prerequisite cycles, audio policy, personalisation fields — and both the app and a command-line tool run the exact same pipeline. Every rule reports a stable code, and a mode decides whether that code is a warning or a hard failure. Dev mode lets me keep building with placeholders visible; release mode refuses to ship one. A test proves the two modes report identical findings and differ only in severity, so nobody can quietly special-case dev mode into skipping a rule.

The rule I’m proudest of: no activity, hint, or parent script may ever say “look at the picture” or “what word would make sense” to identify a word. That is the textbook strategy of a struggling reader, and it is now a failure the validator catches on real content — not a style guideline somebody has to remember at eleven at night.

A model can generate the audio. Only I can approve it.

Every sound a child imitates precisely — an isolated phoneme, a blended word — is top-tier audio, and top-tier audio can be a generated candidate, but it can only be approved by a human listening to it, one asset at a time. There is no bulk approval path and no code path that can mark one approved on my behalf.

The reason isn’t ceremony. A text-to-speech model reads “t” as often as not with a voiced “uh” tail — a schwa — and a corrupted /t/ teaches a child to blend “tuh-at” instead of “t-at.” No automated check can hear that. My ear at the point of approval is the actual safeguard, and the architecture makes that literal: an unapproved top-tier asset fails the build in both modes, permanently.

No gamification, structurally

No emoji, no scores, no streaks, no red failure states, anywhere — there is a test that scans every Swift file and every content string for the emoji Unicode blocks and fails the build if it finds one. Missing a tap after two tries doesn’t produce a failure state; it produces an offer to move on together, logged as “not yet,” which never demotes anything.

Every lesson also has to be complete and delightful with zero photos and zero recordings, because personalisation is layered on top of a stock baseline and never required by it — enforced by an empty-state test on every single renderer.