thetrail

Engineering

How this is built, and which decisions were made early on purpose.

A language product staged along a real long-distance route. This page is the design document, written for someone who wants to know whether the structure holds.

One

The engine is code. A trail is data.

The product teaches Spanish on the Camino Francés first. Almost none of the machinery is about Spanish, and almost none of it is about the Camino. That separation is the first architectural decision and everything else rests on it.

The engine holds what is true of every trail: walk mechanics, the Speak component, the audio and image pipelines, the curator desks, accounts, and progress. A trail is a package of data loaded into that engine. A language pack rides along with it.

The engine and trail pack boundary Engine code on the left holds walk mechanics, Speak, the audio and image pipelines, curator desks, and accounts. On the right, a trail pack holds route stages, encounter scripts, vocabulary, and manifests, and a language pack holds script, direction, voices, and romanization rules. Packs are loaded into the engine as declarations. The boundary between them is the design. CODE DATA The engine Trail-agnostic. Ships once. Walk mechanics and stage order Speak: click any word, hear it Audio and image pipelines Curator desks and the review gate Accounts, progress, payments Route model: ordered stages with a declared finish THE BOUNDARY A trail pack Route stages and encounter scripts Vocabulary Audio and image manifests Culture notes Licensing and spoiler rules A language pack Script, text direction, calendar Voices and romanization rules loaded as declarations
Direction, script, and calendar are declarations in a pack. They are never branches in engine code. Adding a trail means writing a pack, not editing the engine.

The circuit case, decided on day one

The Shikoku pilgrimage is a circle. It ends where it began. A route modelled as a line from a start point to a different end point cannot represent it, and that assumption is cheap to remove now and expensive to remove later.

So a route is an ordered list of stages with a declared finish. A straight walk to Santiago satisfies that. A circuit satisfies it too. The constraint was written into the model before any trail was authored against it.

Two

No generated content reaches a learner without human review.

That sentence is a policy, and policies that live only in tooling get bypassed by the next tool. It is enforced on the server, at the point where content is served, rather than in the desk software a curator happens to use.

Content is authored as a prompt under a shared style preamble, not improvised per asset. Generation runs against that spec. An automated check reads the result and knows which direction the subject should be facing, which catches a class of error that is obvious to a person and invisible to a generic classifier. Only then does a curator see it.

The human-in-the-loop content pipeline An authored prompt under a shared style preamble feeds generation. An automated direction-aware check follows. A curator then reviews. Only approved content is served to a learner. Rejected work returns to the prompt to be rewritten. The curator gate is enforced on the server. Authored prompt style preamble Generation metered, capped Automated check direction-aware Curator review THE GATE Served to a learner rejected, rewritten, generated again EVERY ASSET TAKES THIS PATH
The gate sits on the server. There is no path from generation to a learner that goes around it, which is what makes the mandate a property of the system rather than a promise about a process.

Audio, and verifying a language you cannot read

Recorded audio goes through a desk with a full round trip. The harder problem is verification. A curator who does not read the target language cannot confirm that a recording says what the script says.

The standard gate is blind verification by two independent translation models. Each is given the audio without the source text. Their outputs are compared against the script and against each other. Agreement is evidence. Disagreement sends the asset back before any person is asked to trust it. This runs before curator review, not instead of it.

Three

Encounters recur. Nothing escalates.

A walker meets the same kinds of exchange again at a later stage. The recurrence is the teaching method: familiarity deepens with the forms of the language rather than with a plot. There is no story to follow and no character to become attached to, which is deliberate.

  • Three paces. The pace governs how much a stage may ask of the learner's voice. The methodology behind what each pace may ask was tested rather than assumed.
  • Replay levels. A stage can be walked again at a higher level, against the same content.
  • A proficiency gate. Progress along the route is gated on demonstrated proficiency, not on time spent.

The dialogue boundary

Every conversation is bounded by the teaching purpose and is nearly banal by design. Nothing escalates. No relationship forms or persists. Every choice available to a learner is equally safe.

This is written as the instructions the content is authored against, and it will be written as the instructions any live model is given. It is not a filter bolted on afterwards, because a filter is a list of things someone thought of.

The commercial consequence is worth stating plainly. A product that cannot turn strange is one that a school, a parent, and a tourism board can all put in front of someone without reading every line first. That is what makes a trail shippable in every culture rather than in one.

Four

Security posture, decided as founding requirements.

  • Routes are declared with a gate. Every route carries an explicit gate. The public set is a closed allowlist asserted by a test, and a route that is public carries a written reason for being public.
  • Unauthenticated writes carry a hard cap. The cap is a named constant and it is checked before the write, not after. The invitation form on this site is built that way, with a challenge and a honeypot in front of it.
  • Per-pack content isolation. A shipped bundle must not carry content the learner has not reached, and a pack must not carry another pack's licensed material. One guard covers licensing and spoiler control together.
  • Accounts through OIDC. Progress persists by default for signed-in learners. Consent governs collection rather than attribution, and the privacy policy is linked from the product rather than retrofitted later.

Each of these was a retrofit somewhere before it was a founding requirement here. That is the whole reason they are written down at the start.

Five

The expensive part is the moat.

Authoring is the cost that decides whether this business works. Every encounter is written, generated against a spec, checked, and reviewed by a person who speaks the language. There is no version of this where that gets cheap.

That cost is also the defence. A corpus of reviewed encounters, with recorded audio and checked images across a route of roughly thirty-three stages, is not something a weekend of scraping produces. The mandate that makes it slow is the same mandate that makes it hard to copy.

The bottleneck is curator bandwidth, by design. The plan pays for reviewers rather than bending the rule.