Skip to content
thetrail

Engineering

We made these decisions early, and they hold.

thetrail teaches a language along a real long-distance route.

One

The engine is code. A trail is data.

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

The engine holds what every trail shares: the walk mechanics, the component that speaks a line aloud, the audio and image pipelines, and the walker's progress. A trail is a package of data that the engine loads. A language pack rides along with it.

The engine and trail pack boundary Engine code on the left holds the walk mechanics, the speaking component, the audio and image pipelines, and the walker's progress. On the right, a trail pack holds route stages, encounter scripts, vocabulary, and manifests, and a language pack holds script, direction, and voices. The engine loads packs as declarations. The boundary between them is the design. CODE DATA The engine Trail-agnostic. Ships once. Walk mechanics and stage order Tap any line and hear it Audio and image pipelines The curator desk Progress, kept in the browser 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, calendar, and voices are declarations in a pack. They never become branches in engine code. Adding a trail means writing a pack, and the engine stays as it is.

We decided the circuit case on day one.

The Shikoku pilgrimage is a circle, and it ends where it began. A model cannot represent that walk if it runs from a start point to a different end point. Removing the assumption costs little now and a great deal later.

A route is therefore an ordered list of stages with a declared finish. A straight walk to Santiago satisfies that definition, and a circuit satisfies it too. We wrote the constraint into the model before anyone authored a trail against it.

Two

No generated content reaches a learner without human review.

A new tool can bypass a rule that lives only in tooling. The pipeline that produces content therefore carries the rule, and a founding requirement puts it in the Worker that serves content, which will enforce it once that requirement ships.

An author writes each asset as a prompt under a shared style preamble. Generation runs against that spec. An automated check then reads the result and knows which direction the subject should face. That check catches a class of error a person spots at once and a generic classifier misses. A curator looks at the asset last.

The content pipeline and where the person sits in it An authored prompt under a shared style preamble feeds generation. An automated direction-aware check follows. A curator then reviews. Approved content reaches a learner. Rejected work returns to the prompt for rewriting. 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
Every asset takes this path today, and the tools hold the gate. The founding requirement moves the gate into the Worker that serves the content, which makes the mandate a property of the code.

We verify audio in a language the curator cannot read.

Recorded audio goes through a desk with a full round trip. Verification is the harder problem. A curator who reads no Spanish cannot confirm that a recording says what the script says.

A transcriber therefore hears each clip blind and sees no source text. The desk compares its transcript with the script, after the language pack's rules normalise both. Agreement counts as evidence. Disagreement holds the clip back, and a person decides it. The desk counts an empty transcript as a failure. This check runs ahead of curator review, and it stands in for none 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, and familiarity deepens with the forms of the language. We gave the product no plot to follow and no recurring character to love.

  • Every line has a teaching pace. We are recording a natural pace for every line as well, and the walker will choose between the two once every line has both. The pace governs how much a stage asks of the walker's ear.
  • The trailhead sets the walker's forms and voice. Walkers say there whether they are peregrina or peregrino and how much Spanish they have. They also choose the sentence they will give when someone asks why they are walking. The forms they read and the voice they hear follow those answers for the rest of the road.
  • A wrong answer teaches. A wrong answer costs the walker nothing. The page says why the answer was wrong, and the character asks again.

Every conversation stays inside a boundary.

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

We write the dialogue boundary down as instructions for our authors. Any live large language model (LLM) will get the same instructions. Instructions act before an LLM writes a word. They therefore cover cases the authors did not list.

A school or a parent can put a product that cannot turn strange in front of someone without reading every line first. That property is the commercial reason for the boundary.

Four

Three of the five founding requirements run in full today.

Each of the five arrived as somebody's retrofit on an earlier product, so we wrote them down at the start.

  • An unauthenticated write carries a hard cap. The cap runs today. The invitation form on this site sits behind a challenge and a honeypot, and the server refuses a request that arrives with an empty challenge.
  • A build ships only the files it names. The allowlist runs today. The pack's publish set is an enumerated allowlist, so a file nobody named reaches no visitor, and a test holds the list where it is.
  • Every route declares a gate. The gates run today. The public set is a closed allowlist that a test asserts, and every public route carries a written reason.
  • A pack will carry only its own content. We have not built that guard yet. It will hold back content the learner has yet to reach, and it will keep any other pack's licensed material out, so one guard covers licensing and spoiler control together.
  • Consent will govern what an account collects. Accounts run today. An account saves a signed-in walker's progress and carries it to any browser. The consent step and a privacy policy linked from the product have not shipped yet.

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 pass its language through a blind two-model round trip before a curator signs it off. No version of this work gets cheap.

The authoring cost is also the defence. The trail pack holds reviewed encounters and recorded audio across sixty-six stages. The credits page names the creator and licence of each photograph. The mandate that makes the pack slow to build also makes the pack hard to copy.

The bottleneck is curator bandwidth. The plan pays for reviewers and keeps the rule.