🏃‍♂️ AI Running Coach

Asistente inteligente para corredores amateur con planes personalizados, seguimiento de progreso y coach con IA.

🏗️ Arquitectura

Monorepo con Turborepo que incluye:

• Backend (NestJS): API REST con arquitectura hexagonal
• Frontend (Next.js): Interfaz web moderna con TailwindCSS
• Database: PostgreSQL + Prisma ORM

Arquitectura Hexagonal (Backend)

Domain → Application → Infrastructure
   ↓          ↓              ↓
Entities   Use Cases    Adapters

🚀 Setup Inicial

Prerequisites

• Node.js >= 20
• Docker & Docker Compose
• npm >= 10

Instalación

Opción 1: Script Automatizado (Recomendado)

Windows (PowerShell):

.\start-dev.ps1

Linux/Mac:

chmod +x start-dev.sh
./start-dev.sh

Este script:

• ✅ Crea el archivo .env si no existe
• ✅ Verifica que Docker esté corriendo
• ✅ Inicia PostgreSQL con Docker Compose
• ✅ Limpia procesos Node.js previos
• ✅ Genera el cliente Prisma
• ✅ Inicia Backend (puerto 3001) y Frontend (puerto 3000) simultáneamente

Opción 2: Manual

# 1. Clonar e instalar dependencias
npm install

# 2. Crear archivo .env en la raíz
# Copia el siguiente contenido:
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/ai_running_coach?schema=public"
JWT_SECRET="your-super-secret-jwt-key-change-in-production-12345678"
JWT_EXPIRATION="15m"
JWT_REFRESH_SECRET="your-super-secret-refresh-key-change-in-production-87654321"
JWT_REFRESH_EXPIRATION="7d"
API_PORT=3001
API_PREFIX="api"
FRONTEND_URL="http://localhost:3000"
NEXT_PUBLIC_API_URL="http://localhost:3001/api"
GEMINI_API_KEY="tu-api-key-de-gemini-aqui"

# 3. Levantar PostgreSQL con Docker
docker-compose up -d

# 4. Generar cliente Prisma y ejecutar migraciones
npm run db:generate
npm run db:migrate

# 5. Levantar ambos servicios (Backend + Frontend)
npm run dev

# O individualmente:
npm run dev:api   # Solo Backend (puerto 3001)
npm run dev:web   # Solo Frontend (puerto 3000)

🌐 URLs de Acceso

Una vez iniciado, accede a:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001/api
• Swagger Docs: http://localhost:3001/docs
• Prisma Studio: npm run db:studio → http://localhost:5555
• pgAdmin: http://localhost:5050 (admin@admin.com / admin)

📦 Estructura del Proyecto

ai-running-coach/
├── apps/
│   ├── api/              # Backend NestJS
│   └── web/              # Frontend Next.js
├── packages/
│   ├── database/         # Prisma shared
│   └── typescript-config/
├── docker-compose.yml
└── turbo.json

🔧 Scripts Disponibles

npm run dev              # Backend (3001) + Frontend (3000) simultáneamente
npm run dev:api          # Solo Backend en puerto 3001
npm run dev:web          # Solo Frontend en puerto 3000
npm run build            # Build de producción
npm run lint             # Linter
npm run test             # Tests
npm run db:migrate       # Migrar base de datos
npm run db:generate      # Generar cliente Prisma
npm run db:studio        # Abrir Prisma Studio (puerto 5555)

🚨 Solución Rápida a Errores Comunes

Error: EADDRINUSE: address already in use

Solución:

# Windows
taskkill /F /IM node.exe
npm run dev

# Linux/Mac
pkill node
npm run dev

🧪 Testing API

Registro de usuario

curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "runner@example.com",
    "password": "SecurePass123!",
    "goal": "10K",
    "level": "beginner"
  }'

Login

curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "runner@example.com",
    "password": "SecurePass123!"
  }'

Obtener perfil (protegido)

curl -X GET http://localhost:3001/api/auth/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Crear plan de entrenamiento

curl -X POST http://localhost:3001/api/training/plans \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "10K",
    "level": "intermediate"
  }'

Obtener sesiones de la semana

curl -X GET "http://localhost:3001/api/training/plans/PLAN_ID/weeks/1/sessions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Completar una sesión

curl -X PATCH "http://localhost:3001/api/training/sessions/SESSION_ID/complete" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actualDistanceKm": 10.5,
    "actualDurationMinutes": 60,
    "notes": "Great run!"
  }'

🤖 Configuración de Gemini AI

Para usar el asistente IA necesitas una API Key de Google Gemini:

1. Ve a Google AI Studio
2. Inicia sesión con tu cuenta de Google
3. Haz clic en "Create API Key"
4. Copia la clave y agrégala al archivo .env:

   GEMINI_API_KEY="tu-api-key-aqui"

Notas:

• El modelo usado es gemini-2.0-flash-lite (gratuito)
• Límites del tier gratuito: 15 requests por minuto
• La API Key NO debe compartirse públicamente

---

🏗️ Fases del Proyecto

• Fase 1A: ✅ Setup + Auth MVP (JWT, bcrypt, Prisma)
• Fase 1B: ✅ Training Plans + Sessions (generación de planes, seguimiento de sesiones)
• Fase 2A: ✅ Gemini AI Coach (chat inteligente con contexto, análisis de progreso)
• Fase 2B: Analytics + State Management (Zustand, gráficas de progreso)
• Fase 3: Deploy & CI/CD (Docker, GitHub Actions, Vercel/Railway)

📖 Documentación

Por Fase:

• PHASE-1A-SUMMARY.md - Autenticación JWT completa
• PHASE-1B-SUMMARY.md - Training Plans y Sessions
• TESTING-PHASE-1B.md - Guía de testing para Fase 1B

Configuración y Ayuda:

• PORTS-CONFIG.md - Configuración de puertos
• TROUBLESHOOTING.md - Solución de errores comunes

📝 License

MIT