Multi-tenant AAU basketball program management API

Python 97.6%
HTML 2.3%

Find a file

Lucas Draney c4a95c6782 Some checks failed ci/woodpecker/push/woodpecker Pipeline failed Details feat: payment links table + outstanding balance emails (#524 ) Closes #523 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> # Conflicts: # alembic/versions/048_add_payment_links_table.py # scripts/backfill_payment_links.py		2026-05-18 06:57:05 -06:00
alembic	feat: payment links table, outstanding balance emails, and monthly billing cleanup	2026-05-18 06:31:29 -06:00
data	feat: add sponsor seed data fixture (#323 ) (#327 )	2026-04-04 02:25:54 +00:00
docs	feat: mint tournament-fee checkout URLs as Stripe Payment Links (#494 ) (#496 )	2026-04-17 22:33:59 +00:00
email-templates	feat: add division filter and exclude_ordered to jersey-reminder (#247 )	2026-03-29 19:15:55 +00:00
k8s	fix: use full SHA for image tag (Harbor requires full SHA)	2026-03-24 02:34:26 -06:00
scripts	feat: payment links table, outstanding balance emails, and monthly billing cleanup	2026-05-18 06:31:29 -06:00
src/basketball_api	feat: payment links table, outstanding balance emails, and monthly billing cleanup	2026-05-18 06:31:29 -06:00
templates/email	fix: use transparent logo in action email template (#307 )	2026-04-03 21:29:17 +00:00
tests	feat: mint monthly-fee checkout URLs as Stripe Payment Links (#498 ) (#499 )	2026-04-18 06:06:42 +00:00
.gitignore	feat: MJML email system with brand base + three layouts + docker build compile (#296 )	2026-04-03 19:17:46 +00:00
.pre-commit-config.yaml	feat: standardize ruff config to platform standard (#214 )	2026-03-28 19:10:23 +00:00
.woodpecker.yaml	feat: mint monthly-fee checkout URLs as Stripe Payment Links (#498 ) (#499 )	2026-04-18 06:06:42 +00:00
alembic.ini	Add pal-e-auth integration to gate roster endpoints (#5 )	2026-02-24 04:55:03 +00:00
CLAUDE.md	Add pal-e-auth integration to gate roster endpoints (#5 )	2026-02-24 04:55:03 +00:00
Dockerfile	fix: add mkdir for MJML compiled output directory (#297 )	2026-04-03 19:30:14 +00:00
package.json	feat: MJML email system with brand base + three layouts + docker build compile (#296 )	2026-04-03 19:17:46 +00:00
pyproject.toml	feat: add MCP endpoint with get_schedule tool (#455 )	2026-04-12 19:35:52 +00:00
README.md	docs: rewrite README as portfolio-facing project overview (#228 )	2026-03-28 22:22:32 +00:00

README.md

basketball-api — Youth Basketball Organization API

Production backend powering Westside Kings & Queens, an AAU basketball program in Farmington, NM. Manages the full lifecycle from player registration through team placement, contracts, payments, and game-day operations.

632 tests | 27 migrations | 17 route modules | Zero downtime deploys

Stack

Framework: FastAPI + Pydantic v2, async-ready with SQLAlchemy 2.0
Auth: Keycloak SSO (RS256 JWT validation, realm role extraction)
Database: CloudNativePG (CNPG) PostgreSQL on Kubernetes, Alembic migrations
Payments: Stripe Checkout + webhooks for registration fees and subscriptions
Email: Gmail OAuth integration for transactional emails (confirmations, invites, password resets)
CI/CD: Forgejo + Woodpecker CI + Harbor registry + ArgoCD GitOps

Features

Player Management — Registration flow with email verification, waiver acceptance, and Stripe payment. Admin endpoints for bulk operations, visibility toggles, and interest lead tracking.

Team Rosters — Multi-tenant roster system with division/age group support. Public roster views and JSON API. Many-to-many player-team assignments for flexible placement.

Tryout Tracking — Tryout registration, attendance tracking, and evaluation workflow. Coach scoring integration for data-driven team placement decisions.

Contracts & Coach Onboarding — Digital contractor agreements via Stripe Connect. Token-based onboarding flow with automated email invitations.

Payments & Subscriptions — Stripe webhook processing for one-time fees and recurring subscriptions. Coupon support, payment verification, and admin financial reporting.

Role-Based Access — Four-tier auth model (public, player, coach, admin) enforced via Keycloak realm roles. Protected admin API for program management operations.

Photo Uploads — Player photo management with S3-compatible storage (MinIO). CORS-enabled static serving for frontend consumption.

Password Reset — Self-service password reset flow with tokenized email links and Keycloak account integration.

Architecture

Browser/App ──> FastAPI ──> PostgreSQL (CNPG)
                  │
                  ├──> Keycloak (auth)
                  ├──> Stripe (payments)
                  ├──> Gmail OAuth (email)
                  └──> MinIO (photos)

Development

pip install -e ".[dev]"
export BASKETBALL_DATABASE_URL=postgresql://basketball:basketball@localhost:5432/basketball
alembic upgrade head
pytest                        # 632 tests, ~0.3s collection
python -m basketball_api.main # http://localhost:8000

Deployment

Deployed to a self-hosted k3s cluster via Forgejo push, Woodpecker CI build, Harbor image registry, and ArgoCD sync. Tailscale funnel provides ingress and TLS termination with no external load balancer.