StridePilot — Backend API

REST API for StridePilot, an AI-powered running training application. Built with Express 5, Prisma ORM, and PostgreSQL. Integrates with Anthropic Claude API for AI program generation and Cloudinary for file uploads.

---

Tech Stack

Category	Technology
Runtime	Node.js (ESM)
Framework	Express 5
Language	TypeScript
ORM	Prisma 7
Database	PostgreSQL (Neon serverless)
Authentication	JWT (httpOnly cookie)
Password Hashing	bcrypt
File Upload	multer (memoryStorage) + Cloudinary
AI	Anthropic Claude API
Validation	Zod
Logging	morgan
Package Manager	pnpm

---

Features

• Authentication — Register, Login, Logout with JWT stored in httpOnly cookie
• Role-based Authorization — user / admin roles, free / pro tiers via middleware guards
• AI Program Generation — Generate 4-week training programs via Claude API based on goal, level, days/week, and personal best data
• Session Logging — Log actual pace + HR per km, auto-calculate score /10
• Profile Management — Update profile info and upload avatar to Cloudinary
• Blog/Posts — Admin CRUD with cover image upload
• Admin Panel — Manage user tier and account status

---

Project Structure

src/
├── app.ts                        # Express setup, global middleware, route mounting
├── config/
│   └── env.config.ts             # Zod-validated environment variables
├── controllers/                  # Thin request handlers — parse input, call service, send response
│   ├── auth.controller.ts
│   ├── program.controller.ts
│   ├── profile.controller.ts
│   ├── post.controller.ts
│   └── admin.controller.ts
├── services/                     # Business logic
│   ├── auth.service.ts           # bcrypt hash, JWT sign, Prisma queries
│   ├── program.service.ts        # Claude API call, program save, km log + scoring
│   ├── profile.service.ts        # Profile update, Cloudinary avatar upload
│   └── post.service.ts           # Post CRUD, Cloudinary cover upload
├── middlewares/
│   ├── authenticate.middleware.ts  # Verify JWT cookie → attach req.user
│   ├── tier.middleware.ts          # requirePro: 403 if not pro/admin
│   ├── admin.middleware.ts         # requireAdmin: 403 if not admin
│   ├── uploadFile.middleware.ts    # multer memoryStorage
│   ├── error.middleware.ts         # Global error handler (hides details in production)
│   └── not-found.middleware.ts
├── routes/
│   ├── auth.route.ts
│   ├── program.route.ts
│   ├── profile.route.ts
│   ├── post.route.ts
│   └── admin.route.ts
├── validators/                   # Zod schemas for request body validation
│   ├── register.validator.ts
│   ├── login.validator.ts
│   ├── program.validator.ts
│   └── profile.validator.ts
├── utils/
│   ├── tokenMethod.ts            # JWT sign/verify helpers
│   ├── scoring.ts                # Score /10 algorithm
│   ├── slug.ts
│   └── request.guard.ts
└── db/
    └── generated/prisma/         # Prisma generated client

---

Database Schema

User ──── Profile
User ──< Program ──< Week ──< Session ──< Segment   (pace/HR targets per km range)
                                     └──< KmLog     (actual pace/HR per km)
User ──< Post

• Session types: easy_run | tempo | interval | long_run | recovery | rest
• Segment — km range with paceMin, paceMax, hrMax targets
• KmLog — per-km actual data (actualPace, actualHr)

---

API Endpoints

Auth — /auth

Method	Path	Description
POST	/auth/register	Create account (hashes password with bcrypt)
POST	/auth/login	Login, set httpOnly JWT cookie
POST	/auth/logout	Clear cookie
GET	/auth/me	Get current authenticated user

Programs — /programs

Method	Path	Auth	Description
POST	/programs/generate	Pro/Admin	Generate 4-week AI training program
GET	/programs	Required	Get all user programs
GET	/programs/:id	Required	Get program with full nested data
DELETE	/programs/:id	Required	Delete program
POST	/programs/sessions/:sessionId/log	Required	Log km data, returns session score

Profile — /profile

Method	Path	Auth	Description
GET	/profile	Required	Get profile
PATCH	/profile	Required	Update profile info
POST	/profile/avatar	Required	Upload avatar to Cloudinary

Posts — /posts

Method	Path	Auth	Description
GET	/posts	Optional	Get all published posts
GET	/posts/:slug	Optional	Get post by slug
POST	/posts	Admin	Create post with optional cover image
PUT	/posts/:id	Admin	Update post
DELETE	/posts/:id	Admin	Delete post

Admin — /admin

Method	Path	Auth	Description
GET	/admin/users	Admin	List all users
PATCH	/admin/users/:id	Admin	Update user tier or status

---

Scoring Logic

Each logged km is scored out of 3 points:

Point	Condition
+1	Km was logged (showed up)
+1	actualPace ≤ segment paceMax (skipped if no pace plan)
+1	actualHr ≤ segment hrMax (skipped if no HR plan)

score = (totalPoints / maxPoints) × 10, capped at 10.

---

Environment Variables

DATABASE_URL=
PORT=
NODE_ENV=
ACCESS_JWT_SECRET=
ACCESS_JWT_EXPIRES_IN=
SALT_ROUND=
FRONTEND_URL=
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=
ANTHROPIC_API_KEY=

---

Getting Started

pnpm install
pnpm prisma generate
pnpm dev