Skip to content

README.md

Latest commit

 

History

History
340 lines (234 loc) · 10.4 KB

README.md

File metadata and controls

340 lines (234 loc) · 10.4 KB


DropIt Logo

DropIt: Weightlifting Club Management Application

A web and mobile application to optimize training tracking and management for weightlifting.

Explore the project »

Access Alpha Version · Technical Documentation · Report Bug

📋 Table of Contents
  1. About The Project
  2. Tech Stack
  3. Prerequisites
  4. Installation
  5. Docker Services
  6. Useful Commands
  7. Development
  8. Additional Documentation
  9. License
  10. Contact

🔍 About The Project

DropIt is a web and mobile application designed to optimize training tracking and management for weightlifting.

Main Features: Athlete management, personalized training program creation, exercise library, session planning, and mobile app for performance tracking.

To discover all features in detail, check out the landing page and the technical documentation. (Documentation is in French, as this project started as a school study project)

(back to top)

🛠️ Tech Stack

  • Frontend: React, TypeScript, TanStack (Query + Router), Shadcn/ui + Tailwind CSS
  • Backend: NestJS + MikroORM
  • Database: PostgreSQL
  • Authentication: Better-auth with organization plugin
  • CI/CD: Docker, Docker Compose, GitHub Actions
  • Code Quality: Biome
  • Monorepo: pnpm workspaces

(back to top)

📋 Prerequisites

  • Node.js: Version 22 or higher (required for better-auth and ESM support)
  • pnpm: Package manager version 9.7.1+ (install with npm install -g pnpm@latest)
  • Docker and Docker Compose: For running services (PostgreSQL, PgAdmin, MailDev)
    • Windows/macOS: Docker Desktop must be installed and running before executing Docker commands
    • Linux: Docker Engine and Docker Compose are sufficient

🚀 Installation

1. Clone the project

git clone https://github.com/Netsbump/dropit.git
cd dropit

2. Install dependencies

pnpm install

3. Initial build

To allow packages in packages/ to be used by the different services, you need to perform an initial build:

pnpm build

4. Environment Setup

Automated Setup (Recommended)

The project includes an automated setup script that will:

  • Detect and copy .env.example files to .env (if they don't exist)
  • Check for existing .env files and only prompt for missing variables
  • Prompt you for database configuration (user, password, name, host, port)
  • Prompt you for application ports (API, MailDev, PgAdmin)
  • Detect your local IP address for the mobile app
  • Generate a secure BETTER_AUTH_SECRET automatically
  • Configure all .env files with the correct values
  • Optionally start Docker services (PostgreSQL, MailDev, PgAdmin)
  • Optionally run database migrations or set up a fresh database with seed data
pnpm setup

The script will guide you through the configuration process interactively. After completion, you'll see a summary of all configured services and their URLs.

Manual Setup (Alternative)

If you prefer to configure everything manually:

  1. Copy environment files:
# Root .env file (for Docker Compose)
cp .env.example .env

# API .env file
cp apps/api/.env.example apps/api/.env

# Web frontend .env file (API URL configuration)
cp apps/web/.env.example apps/web/.env

# Mobile app .env file (API URL configuration with local IP)
cp apps/mobile/.env.example apps/mobile/.env

# For production mobile build, also create:
cp apps/mobile/.env.example apps/mobile/.env.production
# Then edit .env.production with your public API URL
  1. Configure environment variables:

Edit each .env file and update the values according to your environment. Key variables to configure:

  • Database: DB_USER, DB_PASSWORD, DB_NAME, DB_PORT, DB_HOST
  • API: API_PORT, BETTER_AUTH_SECRET, BETTER_AUTH_URL, TRUSTED_ORIGINS
  • Mobile: EXPO_PUBLIC_API_URL (use your local IP, e.g., http://192.168.1.XXX:3000)

⚠️ Make sure to update the API URL and port in all .env files to match your configuration.

  1. Start Docker services:
docker compose up -d
  1. Set up the database:

Wait a few seconds for PostgreSQL to fully start, then run migrations or create a fresh database:

# Option 1: Run migrations
pnpm --filter api db:migration:up

# Option 2: Fresh database with seed data
pnpm --filter api db:fresh

5. Start development

pnpm dev

The services will be available at the following URLs:

🐳 Docker Services

The project uses Docker Compose to provide the following services:

  • PostgreSQL: Database server
  • PgAdmin: PostgreSQL administration tool
  • MailDev: SMTP server for development (not for production use!)

⌨️ Useful Commands

Setup

  • Automated setup: pnpm setup

Docker

  • Start Docker services: docker compose up -d
  • Stop Docker services: docker compose down
  • View Docker logs: docker compose logs -f

Development

  • Start all apps: pnpm dev
  • Start web + API only: pnpm dev:web-api
  • Start mobile app only: pnpm dev:mobile
  • Build applications: pnpm build
  • Type checking: pnpm typecheck
  • Lint code: pnpm lint
  • Fix linting issues: pnpm lint:fix
  • Format code: pnpm format

Database (API)

  • Fresh database with seeds: pnpm --filter api db:fresh
  • Run seeds only: pnpm --filter api db:seed
  • Create migration: pnpm --filter api db:migration:create
  • Run migrations: pnpm --filter api db:migration:up
  • Rollback last migration: pnpm --filter api db:migration:down
  • Check pending migrations: pnpm --filter api db:migration:check

Tests

  • Run API unit tests: pnpm test:api:unit
  • Run API integration tests: pnpm test:api:integration

💻 Development

Test Data (Seeds)

Seed data is not created automatically. To populate development data, run:

pnpm --filter api db:seed

This creates test data including:

Web Interface Login

After running seeds, the web app has two login routes:

  • Admin login (email + password): /login/admin (example seeded account: super.admin@gmail.com / Password123!)
  • Member/coach login (email OTP): /login then /login/otp (example seeded account: coach@example.com)

Source of truth for seeded auth data: apps/api/src/seeders/athlete.seeder.ts and apps/api/src/seeders/organization.seeder.ts.

Email Verification in Local Dev (MailDev)

The OTP login flow sends a verification code by email. In local development, use MailDev to read those emails:

After requesting OTP login, open MailDev to retrieve the verification email/code.

Mobile Application (React Native)

A mobile application is available in apps/mobile/. It starts automatically with pnpm dev (which launches all apps in parallel). To test it:

  1. Install Expo Go on your phone
  2. Scan the QR code displayed in the terminal (the mobile app starts with pnpm dev; if the QR code doesn't appear, run the command from the apps/mobile/ folder)

To log in, use one of the users generated by the seeds. Since names and emails are generated by Faker, check the database directly via PgAdmin to retrieve credentials.

PgAdmin Access:

  • URL: http://localhost:5050
  • Email: admin@admin.com
  • Password: admin
  • Universal password for all seeded users: Password123!

(back to top)

📚 Additional Documentation

For deeper technical aspects of the project, check out the following guides:

Deployment and Infrastructure

  • Deployment Guide: Complete production infrastructure configuration (VPS, Dokploy, Traefik, Docker Swarm) (in French)
  • Emergency Recovery Plan: Recovery procedures in case of major failure (in French)

Database Management

(back to top)

📄 License

Distributed under the GNU Affero General Public License v3.0 (AGPL-3.0).

This software is free and open source, but with strong protection against commercial appropriation:

  • ✅ You can freely use, modify, and redistribute this software
  • ✅ Any fork must remain open source under AGPL-3.0
  • ✅ Modifications on a web server must be shared publicly

See the LICENSE.md file for the full license text.

(back to top)

📧 Contact

LinkedIn: Sten Levasseur

(back to top)