DEV Community

Cover image for How I Built an AI Running Coach Pipeline: From Garmin Webhook to Custom GPT
Yury
Yury

Posted on

How I Built an AI Running Coach Pipeline: From Garmin Webhook to Custom GPT

#ai #architecture #chatgpt #nextjs

The Problem

I'm a runner who uses Intervals.icu to track training metrics — CTL (Chronic Training Load), ATL (Acute Training Load), TSB (Training Stress Balance), VDOT, HR zones. Great data platform, but it doesn't tell you what to do next.

ChatGPT can reason about training — but without data, it hallucinates. It'll suggest pace zones for a runner it knows nothing about.

I needed a bridge.

The Architecture 

Garmin Watch
  → Intervals.icu (direct sync, not Strava)
    → Webhook (ACTIVITY_UPLOADED / CALENDAR_UPDATED)
      → Next.js API Route
        → Processing Pipeline
          → PostgreSQL (Prisma)
            → Custom GPT (via Actions API)
              → Plans written back to Intervals.icu calendar
Enter fullscreen mode Exit fullscreen mode

Stack: Next.js 16 (App Router), TypeScript strict, Prisma 7, PostgreSQL 16, grammy (Telegram bots), Mistral API + OpenAI fallback, Docker Compose + Caddy.

The Webhook Handler

When Intervals.icu fires a webhook, the handler needs to:

  1. Validate HMAC-SHA256 signature
  2. Route by event type (activity uploaded, calendar updated, activity deleted)
  3. Return 200 immediately (async processing)
  4. Fetch full activity data (main + intervals + streams)
  5. Run the AI pipeline

The tricky part: Intervals.icu sends the webhook before all data is fully computed. Sometimes CTL/ATL values arrive as null. I added a 30-second delay + retry to handle this.

Session Classification (The Hard Problem)

The naive approach: "if >80% of time is in HR Zone 1-2, it's Easy." This is wrong.

A proper VO2max interval session:

  • 15 min warmup (Z1-Z2)
  • 6×1000m at Z4-Z5 with 3 min recovery (Z1)
  • 10 min cooldown (Z1-Z2)

Total time in Z1-Z2: >70%. It's not easy.

What works: analyzing lap structure.

// Simplified classification logic
const lapPaces = laps.map(l => l.pace) // sec/km
const paceVariance = Math.max(...lapPaces) - Math.min(...lapPaces)

if (paceVariance < 30) {
  // Uniform pace → Easy or Long
  return distance > 15 ? 'Long' : 'Easy'
}

// Has pace alternation → send to AI with lap structure
const lapSummary = laps.map(l => ({
  duration: l.elapsed_time,
  pace: formatPace(l.pace),
  hr: l.avg_hr,
  type: l.pace < avgPace * 0.9 ? 'fast' :
        l.pace > avgPace * 1.1 ? 'slow' : 'medium'
}))
Enter fullscreen mode Exit fullscreen mode

For interval workouts, the AI sees the lap structure — not aggregated HR percentages — and classifies into: Easy, Threshold, Interval_VO2, Long, Recovery, Repetition, Race.

VDOT Calculation (Daniels' Tables)

VDOT from Jack Daniels' Running Formula maps race performance to training zones. The implementation needs a lookup table (VDOT 30-85) with reference columns for each standard distance.

The bug everyone makes: distance-to-column mapping.

function getRefColumn(distanceKm: number): string {
  if (distanceKm >= 42.0) return 'M'   // Marathon
  if (distanceKm >= 20.0) return 'HM'  // Half marathon
  if (distanceKm >= 9.5)  return 'K10' // 10K
  if (distanceKm >= 4.5)  return 'K5'  // 5K
  return 'interpolate' // Sub-5K needs interpolation
}
Enter fullscreen mode Exit fullscreen mode

A 12km race at tempo effort? It falls between 10K and HM columns. Most implementations default to "Threshold" pace reference and get wrong results.

I only calculate VDOT from actual races or top-5% performances by distance — not from easy jogs.

Profile / Connections

The Custom GPT Layer

The GPT reads a structured JSON summary (~50KB) on each conversation:

  • Profile: athlete info, goals, rules, current strategy
  • Recent trainings: last 30 sessions with splits, HR, pace, session type, user reports
  • History: 26 weekly summaries with per-sport breakdowns
  • Pace journal: Daniels zones (plan vs actual)
  • Wellness: HRV, sleep, resting HR with 7-day trends and baseline
  • Condition: AI-generated assessment with risks and recommendations

ChatGPT conversation

The GPT can write events to the Intervals calendar via API Actions. Each workout gets an external_id for idempotent upserts — so cosmetic changes don't create duplicates.

What I'd Do Differently

  1. Start with Zod validation everywhere. Intervals.icu API responses are loosely typed. I added Zod schemas retroactively and found bugs I'd missed.

  2. Event-driven User Summary instead of cron. My first version recalculated every minute (1440 heavy queries/day). Now it triggers on: new training, condition update, GPT request, with a 10-minute TTL.

  3. Encryption for API keys from day one. Started with plaintext storage, moved to AES-256-GCM later. Should have been the default.

  4. Test VDOT with edge cases early. My initial calculation gave ~25% error for certain distances because of the column mapping issue above.

Links

I built this solo. It's free, it's been running in production since early 2026 — dozens of athletes around the world use it daily, and new users keep joining. Happy to answer technical questions in the comments.

Top comments (0)