💪 Trainify API

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

---

📃 About  •   🛠️ Tech Stack  •   ✨ Features  •   🚀 Getting Started  •   🐳 Docker  •   📖 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 API and 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
• 🐳 Docker support with multi-stage build
• 📖 Interactive API documentation with Scalar
• 🧪 Automated testing with Vitest

---

🚀 Getting Started

📋 Prerequisites

• 🟩 Node.js 22+
• 📦 npm
• 🐳 Docker (optional, for containerized setup)

🔧 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 trainify-pg

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

---

🐳 Docker

The project includes a multi-stage Dockerfile that builds the application and produces a lightweight runtime image containing only the compiled output and production dependencies. The .dockerignore keeps secrets, local artifacts and tests out of the image.

🏗️ Building the image

docker build -t trainify-api .

▶️ Running the container

The container does not read .env from the image. Pass the environment variables at runtime:

docker run --env-file .env \
  -e DATABASE_URL="postgresql://docker:docker@host.docker.internal:5432/trainify?schema=public" \
  -p 3333:3333 \
  trainify-api

On Linux, host.docker.internal may not resolve by default. Add --add-host=host.docker.internal:host-gateway to the command, or use the compose setup below.

🧩 Running with Docker Compose

To start the API and the database together:

docker compose up -d --build

Inside the compose network the database host is trainify-pg, which is already set in the trainify-api service, so there is no need to change DATABASE_URL for this setup.

🗃️ Running migrations in the container

Migrations are not executed on container start, to avoid race conditions when running multiple replicas. Run them manually:

docker compose exec trainify-api npx prisma migrate deploy

Or, with a standalone container:

docker exec -it <container_id> npx prisma migrate deploy

🩺 Health check

The image includes a health check that calls GET /health every 30 seconds. You can inspect the status with:

docker ps

---

📖 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