Building iRun AI: An Explainable Running Coach That Refuses to Hallucinate Workouts

I shipped iRun AI — a running coach that turns a goal, a week, and recovery into a training plan, then shows its work.

GPS tracking is a solved product. Trust is not.

The problem I actually wanted to solve

Runners don’t need another black-box “AI plan.” They need to know why Tuesday is a tempo, why the long run got shorter, and whether the race-day number is a forecast or a vibe.

Generative models are great at sounding sure. Training load is a bad place to be sure by accident.

So the constraint became:

Can a coach feel intelligent without ever inventing a workout?

What “explainable” means in the product

For iRun, that meant:

Every prescription traces to a named constant in PlanRules — progression ceilings, recovery-week rhythm, taper factors, intensity budget per phase.
The generator composes those rules. It does not ask a language model what next week should look like.
Every mutation writes a PlanRevision recording why it happened.
The in-app coach proposes a reschedule, skip, or volume ease. The same audited adapter applies it only after the runner accepts.
Medical questions are declined. Injury-risk copy describes a training-load pattern, never a diagnosis.

AI is used for phrasing and summarising evidence. It is never the source of a training constraint.

Race Twin: a simulation, not a fortune cookie

The flagship feature is AI Race Twin — a live model of race day built only from evidence the runner has provided or authorised: completed sessions, reported effort, pace, elevation, optional heart-rate and sleep, missed sessions, declared availability.

It looks at:

a benchmark or experience-derived reference pace
fitness and fatigue as two exponentially weighted averages (a Banister-style load model)
readiness check-ins
the remaining plan, projected forward
scenarios: extra training days, a missed week, a hilly course, heat

What it returns is a finish range, a confidence, and an ordered list of named, weighted factors.

Three rules are structural, not copy:

Ranges, not point values. Width tracks how much evidence exists.
Explainability. Nothing is shown that cannot be justified.
Withhold rather than invent. Below three completed runs, or when confidence drops to insufficient, the prediction is not offered at all.

You can ask “what if I miss next week?” and re-run the twin. The answer changes for a reason you can read.

The coach on the phone is grounded, not generative

The shipping coach (GroundedCoachService) classifies questions into a fixed set of intents and answers from the runner’s own plan, history, and Race Twin output.

That has three product consequences:

it works offline and costs nothing to run
it cannot hallucinate a number, because every number is read from the plan
no health or location data leaves the device for coaching

A cloud coach can be enabled separately, off by default, with explicit consent — because that path would send personal training data to a third party.

Why local-first (and what the backend is not)

A run recorded in a tunnel with no signal is still a first-class run.

The training engine and Race Twin are pure Dart, deterministic: same inputs, same plan. SQLite is the source of truth. Writes land locally first and queue for sync with client-assigned ids so retries don’t duplicate.

The FastAPI backend exists for durable storage, cross-device sync, verified entitlements, and privacy controls. It does not derive the plan. Until an API base URL is baked into the build, the app does not pretend to be syncing.

Privacy is not a paid feature: account deletion, data export, consent withdrawal, and route privacy stay free. Shared maps omit the first and last 250 m.

What I shipped

iRun AI is a Flutter app (Riverpod, SQLite, feature-first screens) plus an optional FastAPI + Postgres sync layer.

Store links:

What I’d still harden

Health integrations that lack credentials should keep saying so — no fake toggles. Cloud coaching, if it ever ships, needs the consent story to stay louder than the feature. And Race Twin will always want more evidence before it speaks; that tension is the product.

The bet I’m proudest of: a coach that can explain a change, and that would rather stay quiet than guess.

If you’re building “AI” into health or training: put the rules in a file a human can read. Let the model talk. Don’t let it decide.