README.md

💪 Trainify API

A REST API for the Trainify app to manage workouts, exercises, sessions, metrics and user progress.

---

📃 About  •   🛠️ Tech Stack  •   ✨ Features  •   🚀 Getting Started  •   📖 API Documentation  •   🧪 Tests

---

📃 About

Trainify API is the backend of the Trainify app, responsible for providing a REST layer to register and track workouts. The application allows managing exercises, creating and finishing workout sessions, logging weight, tracking metrics, and consuming progress data through a well-organized modular structure.

The project was built with Fastify, TypeScript, Prisma ORM and PostgreSQL, with a focus on performance, strong typing, hardened security and interactive documentation via Scalar.

---

🛠️ Tech Stack

• 🟢 Node.js — Server-side JavaScript runtime.
• ⚡ Fastify — Fast and efficient web framework.
• 🔷 TypeScript — Static typing and safer development.
• 🗃️ Prisma ORM — Modern, type-safe ORM for relational databases.
• 🐘 PostgreSQL — Robust relational database.
• 🐳 Docker — Containerization of the local database.
• 🔐 @fastify/jwt — JWT authentication.
• 🍪 @fastify/cookie — Cookie parsing and management.
• 🌐 @fastify/cors — CORS handling.
• 🛡️ @fastify/helmet — Security headers for HTTP responses.
• 🚦 @fastify/rate-limit — Request rate limiting.
• 📖 @fastify/swagger + @scalar/fastify-api-reference — Interactive API documentation.
• 🔑 bcrypt — Password hashing.
• 📅 dayjs — Lightweight date manipulation.
• 🧩 Zod — Runtime schema validation with full type inference.
• 📦 tsup — Bundler for building the production output.
• 🧪 Vitest — Automated testing.
• 🔍 Biome — Fast, opinionated linter and formatter.

---

✨ Features

• 🏋️ Exercise management (catalog and custom exercises)
• 🗓️ Workout creation, plans and weekly scheduling
• ⏱️ Starting, pausing and finishing workout sessions
• 📝 Exercise log tracking and session history
• 📊 Performance comparisons (weekly, monthly and per exercise)
• ⚖️ Weight logging, weight goals and analytics
• 📈 Overall user metrics and progress
• 🏆 Gamification module: streaks, badges and achievements
• 🔐 JWT authentication and Google sign-in
• 🛡️ Security hardening with Helmet and rate limiting
• 🧩 Data validation with Zod
• 📖 Interactive API documentation with Scalar
• 🧪 Automated testing with Vitest

---

🚀 Getting Started

📋 Prerequisites

• 🟩 Node.js 20+
• 📦 npm
• 🐳 Docker

🔧 Installation

1. Clone the repository:

   git clone https://github.com/joschonarth/trainify-api.git

2. Navigate into the project:

   cd trainify-api

3. Install dependencies:

   npm install

🔑 Environment Variables

Copy the example env file and fill in your values:

cp .env.example .env

Example content:

NODE_ENV=dev
PORT=3333
JWT_SECRET=your_jwt_secret
GOOGLE_CLIENT_ID=your-google-oauth-client-id.apps.googleusercontent.com
DATABASE_URL="postgresql://docker:docker@localhost:5432/trainify?schema=public"

🐳 Database

Start the PostgreSQL container:

docker compose up -d

Run the Prisma migrations:

npm run migrate

Optionally, seed the database with sample data:

npm run seed

▶️ Running

Start the server in development mode:

npm run dev

API running at http://localhost:3333

---

📖 API Documentation

With the server running, access the interactive documentation at:

• 📚 http://localhost:3333/docs

There is also a health check endpoint available at:

• ❤️ http://localhost:3333/health

---

🧪 Tests

Tests are run with Vitest and cover the main application flows.

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

---

📁 Project Structure

src/
  modules/
    exercise/
    gamification/
    metric/
    session/
    user/
    weight/
    workout/
  lib/
  env/

---

⭐ Contributing

Contributions are welcome. If you'd like to help, open an issue or submit a pull request with your proposed improvements.

If you liked this project, consider leaving a ⭐ on GitHub — it really helps!

---

Made with ♥ by João Otávio Schonarth