thetrail

Engineering

How this works, and which decisions we made early on purpose.

A language product staged along a real long-distance route. This page is the design document. It answers one question: does the structure hold.

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 model that runs from a start point to a different end point cannot represent that. Removing the assumption costs little now and a great deal 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. We wrote that constraint into the model before anyone authored a single trail against it.

Two

No generated content reaches a learner without human review.

That sentence is a policy, and the next tool always walks around a policy that lives only in tooling. So the Worker enforces it at the moment it serves content, rather than the desk software a curator happens to open.

An author writes each asset as a prompt under a shared style preamble rather than improvising per asset. Generation runs against that spec. An automated check then reads the result and knows which direction the subject should face. That catches a class of error a person spots instantly and a generic classifier never sees. Only then does a curator look at 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 inside the Worker that serves the content. No route reaches a learner without passing through it. That is what makes the mandate a property of the code 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.

So two independent translation models transcribe it blind. Each hears the audio and never sees the source text. The desk then compares both outputs against the script and against each other. Agreement counts as evidence. Disagreement sends the asset back before any person has to trust it. This runs before curator review, never 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. We tested what each pace may ask rather than assuming it.
  • Replay levels. A learner can walk a stage again at a higher level, against the same content.
  • A proficiency gate. The gate opens on demonstrated proficiency, never on time spent.

The dialogue boundary

Every conversation stays inside the teaching purpose and stays nearly banal by design. Nothing escalates. No relationship forms or persists. Every choice a learner can make carries the same weight.

We write that boundary as the instructions our authors work against, and we will hand any live model the same instructions. It is not a filter bolted on afterwards, because a filter only catches the things somebody thought of first.

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.

  • Every route declares a gate. A test asserts the public set as a closed allowlist, and any route that stays public carries a written reason for it.
  • Unauthenticated writes carry a hard cap. The cap is a named constant, and the code counts against it before the write rather than after. The invitation form on this site works exactly that way, behind a challenge and a honeypot.
  • 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 product links its privacy policy from day one instead of retrofitting one later.

Every one of these started life as somebody's retrofit. That is the whole reason we write them down at the start.

Five

The expensive part is the moat.

Authoring is the cost that decides whether this business works. We write every encounter, generate it against a spec, check it, and hand it to a reviewer who speaks the language. No version of this 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.