Barbell

An open dataset allowing FRC teams to upload match images, and download object detection datasets.

Warning

This project is in pre-alpha as of June 24, 2025. Everything is still at the "it works on my machine" point, except it doesn't even work for me! 😅

Note

I don't quite have time in my schedule to work on this right now. The project is not abandoned, and I will come back to it in 2026

Todo:

See issues

Developing

If you are interested in helping, read this, then take a look at issues to see what I am working on.

Libraries Used

• Python 3.10
• FastAPI
• SQLModel
• Jinja
• Bootstrap 5
• Quercus.js
• MJML
• AWS
  • S3
  • PostgreSQL

Project Structure

Barbell/
├── app/                 # The backend python project
│   ├── api/             # The API endpoints
│   ├── core/            # App-level core logic/config
│   ├── crud/            # CRUD interface layer
│   ├── models/          # Data models
│   ├── services/        # Various services and abstractions
│   ├── tasks/           # Asynchronous background tasks
│   ├── tests/           # Tests
│   ├── web/             # Files for the website
│   │   ├── static/      # Static files
│   │   └── templates/   # HTML Jinja templates
│   ├── database.py      # Database managers
│   └── main.py          # Main entrypoint
├── frontend/            # The frontend Node project
│   ├── email_templates/ # MJML email templates
│   ├── js/              # JS
│   │   ├── components/  # General components
│   │   ├── pages/       # Specific pages
│   │   ├── utils/       # Utilities
│   │   ├── index.js     # Dynamically load js depending on page
│   │   └── main.js      # Import libraries
│   └── scss/            # SCSS
│       ├── base/        # Global variables, mixins and more
│       ├── components/  # Styles for common components
│       ├── pages/       # Styles for specific pages
│       └── main.scss    # Main style entrypoint
└── README.md <----------- You are here!

Running Locally

Pre-requirements

• Have git installed
• Have Docker Compose installed
• Have Python 3.10+ installed

Initial Setup

# Clone the repository
git clone "https://github.com/crummyh/Barbell.git" # (Or use ssh)
cd Barbell

# Install uv (if not already installed)
pip install uv

# Create project environment and install dependencies
uv sync

# Set up pre-commit hooks
uv run pre-commit install

# Run setup script
chmod +x ./scripts/setup.sh
./scripts/setup.sh

# Rename environment file
# ⚠️  IMPORTANT: Rename .env.db.example to .env.db !!!

Daily Development Workflow

Starting Development

cd Barbell
# No need to activate virtual environment - uv handles it automatically!

Running the Application

docker compose up --build

Running Tests

./scripts/run-tests.sh

Code Quality Checks

# Format and lint your code (runs automatically on commit)
uv run pre-commit run --all-files

# Run individual tools if needed:
uv run black .                    # Format code
uv run ruff check --fix .         # Lint and auto-fix
uv run mypy .                     # Type checking

Making Commits

# Stage your changes
git add .

# Commit (pre-commit hooks run automatically)
git commit -m "Your commit message"

# If pre-commit makes changes, re-add and commit:
git add .
git commit -m "Your commit message"

Database Connection

psql -h localhost -p 5432 -U myuser -d myappdb

Shutting Down

docker compose down

Adding New Dependencies

Production Dependencies

uv add package-name

Development Dependencies

uv add --dev package-name

Useful Commands

Package Management

uv sync                           # Install/update all dependencies
uv add package-name              # Add production dependency
uv add --dev package-name        # Add development dependency
uv remove package-name           # Remove dependency
uv tree                          # Show dependency tree

Code Quality

uv run pre-commit run            # Run hooks on staged files
uv run pre-commit run --all-files # Run hooks on all files
uv run pre-commit autoupdate     # Update hook versions

Running Scripts

uv run python script.py          # Run Python scripts
uv run uvicorn main:app --reload # Run FastAPI with auto-reload
uv run pytest tests/             # Run specific test directory

Troubleshooting

Pre-commit Issues

# Clean and reinstall hooks
uv run pre-commit clean
uv run pre-commit install

# Skip hooks in emergency (use sparingly!)
git commit --no-verify -m "Emergency fix"

Dependency Issues

# Recreate environment
rm -rf .venv
uv sync

Docker Issues

# Rebuild containers
docker compose down
docker compose up --build --force-recreate