gatorrank

A website for ranking student-made projects at UF.

Table of Contents

• Tech Stack
• Installation
  • Backend
  • Database Migrations (Alembic)
  • Frontend
  • Docker
  • Pre-commit Hooks
• Contributing
  • Workflow
  • CI
  • Branching Strategy

Tech Stack

Backend:

• Python 3.12+
• FastAPI
• Pydantic
• SQLAlchemy
• Supabase
• uv

Frontend:

• TypeScript
• Next.js 16
• Chakra UI
• Bun

Installation

Backend

1. Sync dependencies with uv:

 cd backend
 uv sync

2. Select the Python interpreter in VS Code:

• Press Cmd+Shift+P or Ctrl+Shift+P
• Type "Python: Select Interpreter"
• Choose ./backend/.venv/bin/python3

3. Run the FastAPI server:

 uv run uvicorn app.main:app --reload

The backend server will be available at http://localhost:8000 API documentation (Swagger UI) is available at http://localhost:8000/docs 4. To run backend tests:

 uv run pytest

Database Migrations (Alembic)

Migrations are managed in backend/alembic/ and use the backend DATABASE_URL from backend/.env.

1. Apply all pending migrations:

 cd backend
 uv run alembic upgrade head

2. Create a new migration after changing SQLModel models:

 cd backend
 uv run alembic revision --autogenerate -m "describe schema change"

3. Apply one new migration (or all pending):

 cd backend
 uv run alembic upgrade head

4. Roll back the most recent migration:

 cd backend
 uv run alembic downgrade -1

5. View migration history:

 cd backend
 uv run alembic history
 uv run alembic current

Notes:

• Alembic derives a sync migration URL automatically from DATABASE_URL (you do not need a separate env var).
• Always review autogenerated migration files before running upgrade.

Frontend

1. Install dependencies with bun:

 cd frontend
 bun install

2. Run the Next.js development server:

 bun dev

The frontend will be available at http://localhost:3000

Docker

Docker Compose lets you run both the backend and frontend with a single command instead of starting each server separately. Requires Docker Desktop.

1. Copy the environment files and fill in your values:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

Key values to set:

• backend/.env: DATABASE_URL (your Supabase connection string), CORS_ORIGINS=http://localhost:3000
• frontend/.env: NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

2. Start the full stack (attached mode, recommended):

docker compose -p gatorrank up --build

This runs in your current terminal and streams logs live. Press Ctrl+C to stop the stack.

3. Daily start (attached, no rebuild):

docker compose -p gatorrank up

Note:

• Run either service separately (attached):

  # backend only (attached)
  docker compose -p gatorrank up backend
  # frontend only (attached)
  docker compose -p gatorrank up frontend

• Use detached mode for the full stack:

  # full stack (detached)
  docker compose -p gatorrank up -d
  # stop detached services
  docker compose -p gatorrank down

4. Open the app:

• Frontend: http://localhost:3000
• Backend: http://localhost:8000
• API docs (Swagger UI): http://localhost:8000/docs

5. View logs (useful in detached mode):

docker compose -p gatorrank logs -f backend
docker compose -p gatorrank logs -f frontend

6. If you change backend/.env or frontend/.env, recreate so new env vars are loaded:

docker compose -p gatorrank up -d --force-recreate

7. Run multiple repo clones at once (different ports):

FRONTEND_PORT=3001 BACKEND_PORT=8001 docker compose -p gatorrank1 up
FRONTEND_PORT=3002 BACKEND_PORT=8002 docker compose -p gatorrank2 up
FRONTEND_PORT=3003 BACKEND_PORT=8003 docker compose -p gatorrank3 up

Notes:

• The --build flag rebuilds images when Dockerfile or dependency files change. You can omit it for normal restarts.
• Compose env vars from env_file are loaded at container creation time. If .env values change, use --force-recreate (or remove/recreate the service).
• Keep using the same project name (-p gatorrank) so all commands target the same containers.
• Polling is off by default for speed. If file changes are not detected on your machine, enable polling only when needed: WATCHPACK_POLLING=true CHOKIDAR_USEPOLLING=true docker compose -p gatorrank up -d frontend

Common issue: backend still uses old DATABASE_URL after you edit backend/.env

Pre-commit Hooks

Pre-commit runs a small set of automated checks before commits. In this repo it:

• trims trailing whitespace and ensures files end with a newline
• runs ruff + ruff format for backend Python files
• runs pyright for backend type checking
• runs eslint and tsc --noEmit for frontend linting and type checking
• runs prettier for frontend TypeScript/JavaScript/CSS/JSON/YAML/Markdown files

Install the pre-commit runner once:

uv tool install pre-commit

Then enable the hooks for this repo:

# in the project root
pre-commit install
pre-commit run --all-files

Note: If a pre-commit hook auto-fixes files during git commit, pre-commit will stop the commit so you can review the changes. Re-stage the modified files (e.g., git add <files>) and run git commit again.

Contributing

Workflow

1. Create a feature branch from main
2. Make your changes
3. Open a pull request to main
4. Get review approval before merging

CI

GitHub Actions automatically runs pre-commit run --all-files on every pull request and whenever commits are pushed to or merged into main.

Branching Strategy

• main - Production-ready code
• feature/* - New features and changes
• fix/* - Bug fixes
• refactor/* - Code refactoring
• hotfix/* - Urgent production fixes
• docs/* - Documentation updates
• test/* - Test additions or updates
• style/* - Code style changes