I built a local-first Apple Health recovery briefing that shows its math

I built recovery-trail, a small local-first Apple Health viewer that answers one specific training question:

Should I push today, or should I pull back?

The part I like most is what it does not use.

There is no backend. There is no account. There is no upload. There is no LLM reading your health data and inventing a confident-sounding paragraph.

It is just a browser app, a web worker, some trend math, and a rule trace.

You drop in an Apple Health export.xml, it parses HRV, resting heart rate, sleep, and workout load locally, then it produces a verdict: standard, caution, or deload.

The app is live here:

https://conalh.github.io/recovery-trail/

The source is here:

https://github.com/Conalh/recovery-trail

There is also a sample-data button, so you can try it without using your own export.

Why not use an LLM?

I like LLMs. I use them a lot. This was not a good place for one.

Recovery data is already noisy. HRV can bounce around. Sleep data can be wrong. Workout load can look scary if you only look at one week. If the final layer is also probabilistic, you now have noise on top of noise.

For this project, I wanted the opposite:

• same input, same verdict
• every fired rule visible
• every threshold inspectable
• no natural-language explanation that hides the actual reason
• no model touching private health data

So the app is closer to a tiny rules engine than a chatbot.

The UI can still produce a narrative line, but the verdict itself comes from deterministic logic gates:

• did HRV trend down?
• did resting HR trend up?
• did sleep drop?
• did acute workload spike relative to chronic load?
• did enough signals fire across enough metrics to call it a recovery stack issue?

That last phrase, "logic gates," is the part that makes it fun. The app does not "feel" like it works because it generated a plausible answer. It works because the pieces line up: signal in, math applied, rule fired, evidence shown.

The data stays in the browser

Apple Health exports can be huge. A real export.xml can be hundreds of megabytes. I did not want the app to freeze while reading it, and I definitely did not want to upload that file anywhere.

So parsing happens in a web worker.

The worker streams the file with file.stream().pipeThrough(new TextDecoderStream()), keeps a sliding text buffer, and scans only the tags the app needs:

• HKQuantityTypeIdentifierHeartRateVariabilitySDNN
• HKQuantityTypeIdentifierRestingHeartRate
• HKCategoryTypeIdentifierSleepAnalysis
• Workout

That gives the UI progress updates while the worker extracts just enough structure for the rule layer:

• HRV samples
• resting heart rate samples
• sleep intervals
• workout durations

It is intentionally boring architecture. The file never leaves the page. The worker returns a normalized in-memory object. The main React app evaluates it and renders the briefing.

The core idea: levels and trends are different

One thing I wanted to avoid was treating every metric as a simple red/yellow/green status.

For recovery, a level and a trend are different signals.

Example:

• HRV can be below baseline right now.
• HRV can also be trending downward even if it has not crossed a scary threshold yet.

Those should not be collapsed into the same check.

So the app runs both:

• level rules: where is the metric now?
• trend rules: where is the metric going?

Level rules catch things like:

• 7-day HRV below a 28-day baseline
• 7-day resting HR above a 28-day baseline
• sleep below target
• acute:chronic workload ratio too high

Trend rules catch direction of travel.

The trend logic is ported from my trainer-facing companion project, fit-ontology, and uses two windows side by side.

The dual-window trend detector

Each recovery signal runs two slope estimators:

1. Acute: 7-day ordinary least squares slope on the raw daily series.
2. Chronic: 28-day EWMA-smoothed series, then ordinary least squares on that smoothed line.

Both slopes are normalized by the 28-day baseline standard deviation, so the threshold is in SD/day rather than raw units.

That matters because "2 ms of HRV per day" and "2 bpm of resting heart rate per day" should not be interpreted on the same raw scale. Normalizing makes the trend detector speak in relative movement against the user's own baseline.

The 7-day detector is responsive but noisy. The 28-day detector is slower but better at catching sustained drift.

Then a combiner resolves the two:

• acute-only fires: demote one band
• chronic-only severe fires: surface as mild
• chronic stronger than acute: promote one band
• chronic confirms acute: trust the acute band
• neither fires: no trend rule

That gives the app a useful personality: it reacts to sharp changes, but it does not panic just because one short window got weird.

There is one more safety check. If the composite recovery score is still high, trend signals get demoted again. In other words, if the level picture is excellent, borderline trend math should not dominate the final verdict.

That is the kind of rule I like because it is explicit. You can argue with it. You can tune it. You can test it. It is not hidden behind a prompt.

The verdict is just the maximum fired severity

After the rules run, the final verdict is simple:

• no serious rules: standard
• caution-level rule: caution
• deload-level rule: deload

If enough rules fire across enough different metrics, the app synthesizes a meta-rule:

Recovery stack is down across the board.

That rule is not mystical. It only appears when at least three rules fire across at least three metrics. It is just a framing layer so the UI can say, "this is not one isolated marker."

The important part is that the rule list stays visible. A verdict without evidence is not very useful. A verdict with every fired rule, window badge, and slope value is something you can actually inspect.

The interface is a briefing, not a dashboard dump

The main view is intentionally compact.

Four rows:

• HRV
• resting HR
• sleep
• load

Each row shows daily cells against baseline. Teal means better than baseline. Rust means worse. The right side shows today's value and percentage change.

Below the heatmap, the app writes a short narrative line like:

Through 5/19 everything was at baseline. Then all four metrics rolled over at once and stayed there.

Then it lists the rules that fired.

Each trend rule shows whether the 7-day detector, 28-day detector, or both fired. It also prints the raw SD/day slope numbers. Tapping a rule focuses the relevant metric row. Tapping a metric expands it into a small SVG line chart with the baseline overlay.

There are no charting dependencies. The sparklines and metric chart are hand-rolled SVG because the data shape is narrow and the interaction is specific.

The project is built with:

• Vite
• React 19
• TypeScript
• Tailwind
• a single web worker
• zero backend
• zero analytics
• zero tracking

What worked out

The satisfying part is that the deterministic approach still feels alive.

The sample data is synthetic, but it is shaped like a real recovery slide: HRV down, resting HR up, sleep down, and load elevated. The app catches the rollover and produces a deload verdict. More importantly, it shows why.

That is the win for me.

Not "AI says you should rest."

More like:

HRV is off baseline across both the 7-day and 28-day windows. Resting HR is rising in the acute window. Sleep is below target. Multiple metrics are down at once.

That is less magical and more useful.

Things I would still improve

The current version is exploratory. It is not medical advice, and it is not trying to prescribe training for everyone.

The next pieces I would like to improve are:

• more fixture coverage around the trend combiner
• better handling for sparse Apple Health exports
• clearer language for "standard" days, not just bad days
• optional export/share of the rule trace
• more tuning against real-world edge cases

There is also a small lint cleanup left in the repo right now, even though the production build passes.

Try it

Live app:

https://conalh.github.io/recovery-trail/

Source:

https://github.com/Conalh/recovery-trail

Click "Try with sample data" if you just want to see the briefing.

If you use your own Apple Health export, the data stays local. The browser parses it, the rules run client-side, and the result is just a visible trail of math.

That is the whole point of the project: not a black box, not a model, just an explainable recovery trail.