Coach Spark

Less tired. More energy. We uncover what’s draining you — and help you change it, one small habit at a time.

Comment

Coach Spark

Energy Intelligence Coach — a mobile app that explains why you feel tired and tells you what to change today. Feeling-first, not score-first.

Coach Spark fuses a one-off blood test, self-reported energy, declared behaviors, and passive health data into a single LLM call per touchpoint. The output is a short, causal brief the user finds surprising by day 14 — not a vague wellness score.

Status: hackathon build. Backend phase 1 complete; phases 2–4 in progress. Frontend scaffolded with mock data; not yet wired to the backend.

Why Coach Spark exists

The problem

Knowledge workers in their 20s–40s are chronically, unexplainably tired. They crash at 3pm, wake up foggy after eight hours of sleep, and google "why am I always tired" more often than they'd like to admit. They've tried the obvious things — sleep trackers, blood panels, productivity apps, supplements, cold plunges — and still can't answer the simplest question about their own body:

Why do I feel this way today?

Why the existing tools don't answer that question

  • Wearables score; they don't explain. WHOOP tells you your recovery is 42%. Oura tells you your readiness is low. Neither tells you why you actually feel bad today — and both produce a nagging dissonance the moment the score contradicts how you actually feel.
  • Blood tests are one-off PDFs. A yearly panel catches the biomarker deficiencies (ferritin, vitamin D, TSH, B12, hemoglobin, fasting glucose, CRP) that explain a huge fraction of daily fatigue — but nobody connects those lab numbers to today's 3pm crash.
  • Wellness apps assume the problem is effort. Calories, steps, streaks, guilt. But most tired knowledge workers aren't short on willpower; they're short on a causal story. Telling them to try harder makes it worse.
  • LLM-wrapped coaches hallucinate medical claims because they have no grounding in fixed biomarker thresholds or longitudinal personal data.

The result: a generation collects more health data than any before it, and still can't say why they're tired.

What we believe

  1. The user's feeling is the truth. Self-reported energy is the target variable — never a score the app imposes on top. Passive data (sleep, HRV, screen time, weather) explains the feeling; it never overrides it. This is the opposite of the WHOOP/Oura paradigm and the single most important design call in the product.
  2. Transparency changes behavior — willpower doesn't. People don't change habits because an app tells them to. They change when they see the causal link in their own data: "when I sleep under six hours **and* eat lunch after 1pm, my 3pm crash is three times worse."* That's their personal rule, discovered from their own numbers, and willpower becomes optional after that. The whole daily loop exists to make that proof visible.
  3. Medical-grade facts belong in code, not in prompts. Seven biomarkers are evaluated against fixed thresholds in Python and injected as facts into the LLM prompt. The LLM narrates the context; it never decides whether a value is abnormal. This rule is non-negotiable — see the domain rules section below.
  4. The daily surface area has to be tiny. Sixty seconds a day, one tap per behavior. If the check-in takes two minutes, users quit by week three and the correlation engine starves before it can produce its first magic moment.
  5. Value must land fast — and compound. Day 1: blood alerts explain known risks. Day 5: personal baselines are established. Day 14: the moment magique — a surprising, personal correlation the user didn't see coming. That's when they convert to paid; that's also when the product stops being generic and becomes theirs.

Who it's for

Primary: knowledge workers aged 25–45 dealing with brain fog, afternoon crashes, and unexplained fatigue — people who already collect health data but have no causal story connecting it to how they feel.

Not for: athletes chasing marginal performance gains (WHOOP already serves them well), clinical patients needing a diagnosis (that's a doctor's job), or anyone looking for a calorie counter or a meal plan. Coach Spark is about energy, not health in the medical sense, and not nutrition in the macros sense.

The one-line thesis

We uncover what's draining your energy — and help you change it, one small habit at a time. No scores. No guilt. Just the why.

Repo layout

coach-spark/
├── backend/       # FastAPI (Python 3.11) — REST API, LLM, biomarker engine
├── frontend/      # Expo / React Native (TS) — mobile app
├── docs/          # Product blueprint + behavior catalog (source of truth)
└── .planning/     # GSD planning artifacts (local-only, gitignored)

Monorepo — backend and frontend are independent (no shared lockfile). Each has its own README.md with setup and status.

Area Owner Stack See
Backend Luca Python 3.11, FastAPI, Postgres 16, Mistral backend/README.md
Frontend Friend (TBD) Expo Router v6, React Native, Zustand frontend/README.md
Product Shared docs/Energy_Intelligence_Coach_Blueprint_v3.md docs/

What this product actually does

Five workflows, all driven from the blueprint:

  1. W1 — Onboarding. User fills a short profile, uploads a blood test, talks to an ElevenLabs voice agent. Backend runs biomarker thresholds in Python, extracts 5–8 initial behaviors from the transcript via Mistral.
  2. W2 — Morning check-in. Daily questionnaire → feeling capture → Mistral generates a 3-card brief: short / detail / summary.
  3. W3 — Evening check-in. Residual logs + energy pulse → evening summary.
  4. W4 — Behavior lifecycle. Accept / dismiss / retire behaviors under a hard cap of 8–9 active slots, enforced server-side.
  5. W5 — Passive data. Read-only consumer of passive_daily_summaries (populated by a parallel Thryve workstream — not owned here).

Domain rules that affect every file in this repo

Violating any of these produces correct-looking code that breaks the product. Full context in CLAUDE.md.

  1. Blood-test thresholds run in Python, never in the LLM. Biomarker alerts are computed from fixed thresholds and injected as facts into the prompt. Medical hallucination is non-negotiable.
  2. Max 8–9 active behaviors per user. Enforced at the data layer, not just the UI.
  3. "Yes" is always the victory. For negative behaviors ("no coffee after 2pm"), true still means the user won. Inversion lives at the question- phrasing layer, never in storage.
  4. Behaviors come from a fixed catalog of 140 items — 87 trackable. Never invented in code.
  5. The app never diagnoses. Flag medical-adjacent copy for review.
  6. Feeling-first. Self-reported energy is the target variable. Passive data explains the feeling; it never overrides it.

Data format conventions (backend ↔ frontend)

  • JSON on the wire: camelCase. Python internals stay snake_case; translate at the Pydantic boundary.
  • Dates: ISO 8601, UTC in storage, localized at display.
  • IDs: UUID v4, generated server-side.
  • Language: English everywhere — code, identifiers, comments, commits, and user-facing copy. (Reversed from the original French-UI decision in April 2026; the blueprint in docs/ remains in French as historical context.)

Getting started

Each subproject runs independently. Start the backend first if you want real data; otherwise the frontend runs happily against its mock layer.

# Backend (Postgres + FastAPI via docker-compose)
cd backend && docker compose up

# Frontend (Expo dev server, any second terminal)
cd frontend && npm install && npx expo start

See each subproject's README for details, env vars, and troubleshooting.

Status at a glance

Track Done Next
Backend phase 1 Infra, DB, Mistral client, biomarker engine, RFC 7807 errors —
Backend phase 2 Onboarding persistence, voice session, webhook receiver Mistral extraction & result polling
Backend phase 3 — Morning/evening check-in + brief + slot cap
Backend phase 4 — Passive data seam + end-to-end demo script
Frontend Route skeleton, onboarding flow, mock-driven today screen Real API wiring, voice agent, blood upload

Detailed phase breakdown in .planning/ROADMAP.md (local-only) and backend/README.md.

Planning workflow (GSD)

This repo uses GSD (Get Shit Done) for planning, tracked in .planning/ — which is gitignored on purpose. Each phase has a PLAN.md, and state is persisted in .planning/STATE.md. You don't need GSD to contribute; it's Luca's assistant-driven workflow, not a team requirement.

If you're using Claude Code, CLAUDE.md at the repo root is the shared "brain" — domain rules, conventions, things to ask before doing. Read it before making non-trivial changes.

Conventions

  • Commits: Conventional Commits (feat:, fix:, docs:, chore:, refactor:). Subject in lowercase, no trailing period.
  • Branch: default is main.
  • PRs: reference the blueprint section when adding product behavior.

Links

Built With

Share this project:

Updates