Runner

AI-powered running coach — personalized periodized plans, smart activity tracking, and social accountability.

---

Overview

Runner is a full-stack web application that acts as your personal AI running coach. Generate dynamically-scaled training plans from today to race day, log activities via GPX or manual entry, sync with Strava, get weekly AI coaching insights, and compete on social leaderboards.

Features

• AI Training Plans — Gemini 2.5 Flash builds a periodized plan scaled to your race date, with phases from base building through taper and precisely prescribed paces, HR zones, and intervals.
• Google Sign-In — One-click authentication via Google OAuth with auto-provisioned profiles.
• Activity Tracking — Upload GPX files, link Strava activities, or log manually. Sessions auto-link to your training plan.
• Strava Sync — OAuth integration with webhook-based auto-import of completed activities.
• AI Coach — Weekly natural-language summaries analyzing volume, pace trends, and adherence.
• Social — Create groups, give kudos, and compete on distance leaderboards.
• Calendar Export — One-click .ics export for Google Calendar, Apple Calendar, or Outlook.

---

Architecture

React 19 + Vite  ←→  Express.js 5 API  ←→  Supabase (Postgres + Auth)
   Tailwind v4        Gemini 2.5 Flash
   shadcn/ui          Strava OAuth

• Frontend: React 19 SPA with Tailwind CSS v4, shadcn/ui components, and Framer Motion animations.
• Backend: Express.js 5 REST API with rate-limited Gemini integrations and Strava webhook handling.
• Database: Supabase (PostgreSQL) with Row-Level Security, authentication, and real-time subscriptions.

---

Getting Started

Prerequisites

• Node.js 18+
• A Supabase project
• A Google Gemini API key
• Google OAuth credentials (for social sign-in)

Setup

# Backend
cd backend
cp .env.example .env    # add your API keys and Supabase credentials
npm install
npm run dev

# Frontend (separate terminal)
cd frontend
cp .env.example .env
npm install
npm run dev

---

Deployment

• Frontend: Deploy to Vercel (set root directory to frontend, framework preset Vite).
• Backend: Deploy to Railway, Render, or Fly.io (set root directory to backend).

---

Tech Stack

Frontend	Backend	Infrastructure
React 19	Express.js 5	Supabase (Postgres + Auth)
Vite 6	Node 18+	Google Gemini 2.5 Flash
Tailwind CSS v4	—	Strava OAuth 2.0
shadcn/ui + Framer Motion	—	—

---

License

MIT