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.

License

Private. All rights reserved.