Fantasy Basketball Analytics Tool

A fantasy basketball analytics platform that pulls player data, injury reports, and league standings to surface player value, volatility, matchup quality, breakout candidates, and trade evaluation.

Quick start (development)

# 1. Configure environment
cp .env.example .env
# Edit .env to set YAHOO_CLIENT_ID, YAHOO_CLIENT_SECRET, etc.

# 2. Start the dev stack (PostgreSQL + Redis + backend + celery + frontend)
docker compose up -d

# 3. Open the app
open http://localhost:5173

The dev stack uses bind mounts, hot-reload, and the Vite dev server. Source edits reflect without restart.

Quick start (production, on the server)

See docs/DEPLOYMENT.md for the full guide.

# After running the one-time setup in docs/DEPLOYMENT.md:
./scripts/deploy.sh

The deploy script pulls prebuilt images from the registry, runs migrations, brings up the stack, waits for the backend to be healthy, smoke-tests the public URL, and rolls back automatically on failure.

Documentation

Doc	Purpose
docs/DEPLOYMENT.md	First-time server setup, day-to-day deploy, troubleshooting
docs/HTTPS.md	Traefik + Let's Encrypt configuration
docs/CLOUD_MIGRATION.md	Checklist for moving from self-hosted to managed cloud
docs/LOCAL_DEVELOPMENT.md	Running the app without Docker (for development on Windows)
.forgejo/runner/README.md	Setting up the Forgejo Actions runner on the server
plans/architecture-plan.md	Feature spec, model descriptions, service boundaries

Architecture

        ┌─────────────────────────────────────┐
        │  Browser                            │
        │  https://fantasy.firmanserver.com   │
        └────────────────┬────────────────────┘
                         │
                  ┌──────▼──────┐
                  │   Traefik   │   (TLS termination, ACME)
                  └──┬──────┬───┘
                     │      │
       ┌─────────────▼┐    ┌▼──────────────┐
       │  Frontend    │    │  Forgejo       │
       │  (nginx)     │    │  (code + CI +  │
       │  :8080       │    │   registry)    │
       └──────┬───────┘    └───────────────┘
              │ /api/*
       ┌──────▼───────┐
       │  Backend     │   FastAPI on :8000
       │  (uvicorn)   │   with Sentry + Pydantic v2 settings
       └──┬───────┬───┘
          │       │
   ┌──────▼─┐  ┌──▼──────┐
   │  DB    │  │  Redis  │   PostgreSQL 15 + Redis 7
   │  (pg)  │  │         │   + daily backup sidecar
   └────────┘  └─────────┘

  ┌────────────────┐
  │  Celery worker │  Scheduled tasks (refresh injuries, sync data)
  │  (background)  │  shares the backend image, different command
  └────────────────┘

Repo layout

backend/                FastAPI app
  app/
    api/                HTTP routers
    models/             SQLAlchemy ORM models
    services/           Business logic (NBA data, value calc, etc.)
    config.py           Settings + validators
    database.py         Async engine + session factory
    main.py             App factory, Sentry init, lifespan
  alembic/              Database migrations
  scripts/              One-off data + ops scripts (operational; archive in _archive/)
  tests/                (TODO: add pytest suite)
  Dockerfile            Multi-stage, prod-shaped
  requirements.txt
frontend/               React + Vite + TypeScript
  src/
    pages/              Route components
    components/         Reusable UI
    api.ts              Generated/manual API client
  nginx.conf            SPA + reverse-proxy config
  Dockerfile            Multi-stage, prod-shaped
.dockerignore
docker-compose.yml      Dev stack (5 services, hot reload)
docker-compose.prod.yml Production stack (Traefik labels, named volumes, backup)
.env.example            Dev env vars
.env.prod.example       Prod env vars (template)
scripts/                Operational helpers
  deploy.sh             Production deploy with health check + rollback
  generate-secrets.sh   Emit strong SECRET_KEY and DB password
  configure-docker-insecure-registry.sh
.forgejo/workflows/     CI + image build (GitHub Actions-compatible)
.forgejo/runner/        Runner setup docs
docs/                   DEPLOYMENT, HTTPS, CLOUD_MIGRATION, LOCAL_DEVELOPMENT
plans/                  Architecture, features, design notes

Observability

• Sentry: error tracking for the backend. Set SENTRY_DSN in .env (dev) or .env.prod (prod) to enable. To switch to self-hosted GlitchTip, replace the DSN — no code changes.
• Health checks: every container has a HEALTHCHECK. Docker Compose depends_on: condition: service_healthy chains them properly.
• Logs: structured JSON to json-file driver with 10MB × 3 file rotation. Tailed via docker compose logs -f.

License

Personal project. (Add a license if/when you want to share or open-source.)