ATP Volleyball Team Website

A modern, full-stack volleyball team management website with roster, stats, and video galleries.

A modern, responsive volleyball team management website with roster, stats, and video galleries.

🏗️ Architecture

• Frontend: React 19 + TypeScript + Vite → GitHub Pages (free)
• Backend: FastAPI + Python → Render (free tier)
• Database: MongoDB Atlas M0 (free tier, 512MB)

🚀 Quick Start

1. Clone and Setup

# Clone the repository
git clone https://github.com/castellbranco/ATP-website.git
cd ATP-website

# Run setup script (creates .env files)
chmod +x setup.sh
./setup.sh

2. Configure Environment Variables

Frontend (.env):

VITE_API_URL=http://localhost:8000
# For production builds set:
# VITE_API_URL=https://atp-volleyball-api.onrender.com

Backend (backend/.env):

MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/...
DATABASE_NAME=atp_volleyball
ADMIN_TOKEN_SECRET=your-secret-here

🔄 CI/CD Pipeline

GitHub Actions automatically runs tests on every PR and deploys to GitHub Pages:

• Tests: Run on every pull request (frontend + backend)
• Deploy: Automatic deployment to GitHub Pages on push to dev
• Status: Check badges at the top of this README

View workflow runs in the Actions tab.

🛠️ Local Development

See backend/.env.example for detailed instructions.

3. Run Locally

Terminal 1 - Backend:

cd backend
pdm install          # or: pip install -r requirements.txt
pdm run dev          # or: uvicorn app.main:app --reload

Terminal 2 - Frontend:

npm install
npm run dev

Visit: http://localhost:5173

🚦 Choose Your Deployment Path

Pick the guide under deployment/ that matches how you like to work:

• QUICK-DEPLOY.md – 5-minute GitHub Pages push for a frontend-only launch.
• DEPLOYMENT-CHECKLIST.md – Complete checklist that covers frontend, backend, and MongoDB with status boxes.
• DEPLOYMENT-CHECKLIST-RENDER.md – Render-specific variant if you're hosting everything there.
• DEPLOYMENT.md – Long-form reference with troubleshooting notes and background context.
• DEPLOYMENT-SETUP-SUMMARY.md – One-page TL;DR plus the exact commands to run.
• RENDER-DEPLOYMENT.md – Full Render walk-through powered by deployment/render.yaml.

Deployment Phases At A Glance

• Phase 1 – Frontend only (≈5 min): push the repo to GitHub, enable Pages, confirm the SPA loads (data is ephemeral).
• Phase 2 – Full stack (+≈30 min): provision MongoDB Atlas, deploy the FastAPI backend (Render/Railway), set VITE_API_URL, and verify admin CRUD.

⚡ Super Quick Frontend Deploy

# Push your latest changes
git add .
git commit -m "Deploy volleyball app"
git push origin dev

🏗️ What You're Deploying

• Frontend (React SPA) – Lives in src/, deploys to GitHub Pages, renders roster, stats, videos, and admin UI.
• Backend (FastAPI) – Lives in backend/, deploys to Render/Railway, exposes REST endpoints for persistent data.
• Database (MongoDB Atlas) – Stores players, stats, videos, and admin accounts that power the backend.

✅ Success Checklist

• Code lives on GitHub and CI passes.
• GitHub Pages serves the site at https://<user>.github.io/<repo>/.
• Backend health check (/health or /docs) responds from Render/Railway.
• Admin panel loads with ?admin=true, accepts credentials, and saves data.
• Added players/stats persist across refreshes.

🆘 Need Help?

• Use the troubleshooting sections inside deployment/DEPLOYMENT.md for build, backend, or database issues.
• Inspect GitHub Actions logs for frontend build errors and Render logs for backend issues.
• Search the exact error message—most fixes are already documented in those guides.

🔌 Frontend ↔ Backend Sync

• src/App.tsx now bootstraps roster, stats, and season data from VITE_API_URL on load. The existing Spark/IndexedDB store remains as a local cache that powers the public tabs and the admin UI.
• Backend exposes a GET /snapshot endpoint that returns all public data in one shot; the SPA now relies exclusively on this endpoint for reads, keeping free-tier traffic to a single request per load.
• Local development: keep VITE_API_URL=http://localhost:8000 and run backend (pdm run dev).
• Production build: set VITE_API_URL=https://atp-volleyball-api.onrender.com (or your Render URL) before running npm run build.
• GitHub Pages deploy workflow already passes along the VITE_API_URL secret—set it in Settings → Secrets → Actions so production builds point to the Render API automatically.

📦 Full Deployment Guide

Want to deploy to production? See RENDER-DEPLOYMENT.md for a complete step-by-step guide to deploy:

• Backend to Render (free)
• Database on MongoDB Atlas (free)
• Frontend to GitHub Pages (free)

Total cost: $0/month 🎉

🛠️ Development

Frontend Commands

npm run dev          # Start dev server
npm run build        # Build for production
npm run preview      # Preview production build
npm run lint         # Run ESLint

Backend Commands

cd backend
pdm run dev          # Development server with auto-reload
pdm run start        # Production server

API Documentation: http://localhost:8000/docs

🧪 Testing

Frontend Tests

The frontend uses Vitest and React Testing Library for testing.

# Run all frontend tests
npm run test

# Run tests in watch mode
npm run test -- --watch

# Run tests with UI
npm run test:ui

# Run tests with coverage
npm run test:coverage

Test Coverage:

• UI Components (Button, Badge, Card)
• Custom Hooks (useIsMobile)
• Utility Functions (cn)
• Total: 29 frontend tests

Backend Tests

The backend uses pytest for testing.

# Navigate to backend directory
cd backend

# Install dependencies
pip install -r requirements.txt

# Run all tests
pytest tests/ -v

# Run tests with coverage
pytest tests/ -v --cov=app --cov-report=term-missing

# Run specific test file
pytest tests/test_players.py -v

Test Coverage:

• Player Routes/Endpoints (12 tests)
• Stats Routes/Endpoints (9 tests)
• Season Routes/Endpoints (7 tests)
• Service Layer (14 tests)
• Models/Data Validation (11 tests)
• Total: 50 backend tests

🎨 Code Quality

The project includes automated code formatting and linting tools to maintain code quality and consistency.

Pre-commit Hooks

The repository uses pre-commit to automatically check and format code before commits:

# Install pre-commit (if not already installed)
pip install pre-commit

# Install the git hooks
pre-commit install

# Run pre-commit manually on all files
pre-commit run --all-files

Frontend Pre-commit

Format and lint frontend code:

npm run precommit

This runs:

• ESLint - Lints and auto-fixes JavaScript/TypeScript code
• Prettier - Formats code for consistent style

Individual commands:

npm run lint         # Lint code
npm run lint:fix     # Lint and auto-fix
npm run format       # Format with Prettier

Backend Pre-commit

Format and lint backend code:

cd backend
pdm run precommit

This runs:

• isort - Sorts Python imports
• black - Formats Python code
• flake8 - Lints Python code

Individual commands:

pdm run isort app/ tests/    # Sort imports
pdm run black app/ tests/    # Format code
pdm run flake8 app/ tests/   # Lint code

Tools Used

Frontend:

• ESLint - JavaScript/TypeScript linter
• Prettier - Code formatter

Backend:

• Black - Python code formatter
• isort - Import sorter
• Flake8 - Python linter

Both:

• pre-commit - Git hook framework

📁 Project Structure

ATP-website/
├── src/                    # Frontend React app
│   ├── components/
│   │   ├── sections/       # Main page sections
│   │   ├── admin/          # Admin components
│   │   └── ui/             # shadcn/ui components
│   ├── hooks/              # Custom React hooks
│   ├── lib/                # Utilities & API config
│   └── App.tsx             # Main app component
│
├── backend/                # FastAPI backend
│   ├── app/
│   │   ├── main.py         # FastAPI app entry
│   │   ├── config.py       # Configuration
│   │   ├── database.py     # MongoDB connection
│   │   ├── models/         # Pydantic models
│   │   ├── routes/         # API endpoints
│   │   └── services/       # Business logic
│   ├── requirements.txt
│   └── pyproject.toml
│
├── .github/workflows/      # GitHub Actions
│   └── deploy.yml          # Auto-deploy to GitHub Pages
│
├── deployment/             # Deployment docs & configs
│   ├── render.yaml
│   ├── DEPLOYMENT.md
│   ├── DEPLOYMENT-CHECKLIST.md
│   ├── DEPLOYMENT-CHECKLIST-RENDER.md
│   ├── DEPLOYMENT-SETUP-SUMMARY.md
│   ├── QUICK-DEPLOY.md
│   └── RENDER-DEPLOYMENT.md

🔧 Technologies

Frontend

• React 19 with TypeScript
• Vite for blazing-fast builds
• Tailwind CSS v4 for styling
• shadcn/ui component library
• Framer Motion for animations
• Recharts for data visualization

Backend

• FastAPI for modern Python APIs
• MongoDB with Motor async driver
• Pydantic for data validation
• python-dotenv for environment management

🌐 Deployment

Frontend (GitHub Pages)

1. Go to Settings → Pages
2. Source: GitHub Actions
3. Add secret: VITE_API_URL with your Render backend URL
4. Push to main branch → Auto-deploys!

Backend (Render)

1. Connect your GitHub repo to Render
2. Use the included deployment/render.yaml for one-click setup
3. Add environment variables (MongoDB URI, secrets)
4. Deploy!

See RENDER-DEPLOYMENT.md for detailed instructions.

🔐 Security

• Never commit .env files (already in .gitignore)
• Generate strong secrets: openssl rand -hex 32
• Use environment variables for all credentials
• MongoDB Atlas IP whitelist configured
• CORS properly configured for production

📚 Documentation

• deployment/QUICK-DEPLOY.md - 5 minute GitHub Pages launch.
• deployment/DEPLOYMENT-CHECKLIST.md - Step-by-step full stack checklist.
• deployment/DEPLOYMENT-CHECKLIST-RENDER.md - Render-specific tasks.
• deployment/DEPLOYMENT-SETUP-SUMMARY.md - One-page overview + prereqs.
• deployment/DEPLOYMENT.md - Long-form reference + troubleshooting.
• deployment/RENDER-DEPLOYMENT.md - Full Render walkthrough and render.yaml.
• Backend API Docs - Swagger UI (when running)
• backend/README.md - Backend-specific setup

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test locally
5. Submit a pull request

📄 License

MIT License - feel free to use this project!

---

Made with ❤️ for ATP Volleyball Team