playersedge/README.md

# PlayersEdge – Athlete Stats Platform

A full-featured PWA for tracking athlete biometric and sports statistics across 5 sports: American Football, Hockey, Baseball, Soccer, and Basketball.

---

## Features

- **5 Sports** with 16 stats each: Football, Hockey, Baseball, Soccer, Basketball
- **Athlete registration** with 4-step form: personal info, biometrics, sport stats, review
- **Multi-sport athletes** – one profile, multiple sports
- **Stat Leaders board** – top 25/50/100 athletes, sort by any numeric stat
- **Advanced filter/search** – filter by any stat, biometric, sport, position, name, city
- **Athlete profiles** – biometrics, all sport stats, social media, contact info, profile photo
- **125 seed athletes** (25 per sport, some multi-sport) with realistic fake data
- **PWA installable** – iOS & Android home screen install
- **Responsive design** – mobile-first with bottom navigation on mobile
- **localStorage persistence** – data survives page refresh
- **Dark sports theme** – high-contrast dark UI with accent colors

---

## Quick Start (Local Development)

```bash
# Prerequisites: Node.js 18+ installed
node --version   # must be 18+

# Install dependencies
npm install

# Start dev server (hot reload, runs on http://localhost:5173)
npm run dev

# Build for production
npm run build

# Preview production build locally (http://localhost:4173)
npm run preview
```

---

## Ubuntu 24.04 LXC Installation

### Prerequisites
- Ubuntu 24.04 LXC container or bare metal
- Root or sudo access
- Ports 80 (and optionally 443) open

### Step 1 – Transfer files to your server

**Option A: Git (recommended)**
```bash
# On your server
apt-get install -y git
git clone https://your-repo-url.git /opt/statsphere-src
cd /opt/statsphere-src
```

**Option B: SCP / SFTP**
```bash
# From your local machine
scp -r ./statsphere root@YOUR_SERVER_IP:/tmp/
ssh root@YOUR_SERVER_IP
cp -r /tmp/statsphere /opt/statsphere-src
cd /opt/statsphere-src
```

**Option C: Upload zip**
```bash
apt-get install -y unzip
unzip statsphere.zip -d /opt/statsphere-src
cd /opt/statsphere-src
```

### Step 2 – Run the installer
```bash
chmod +x install.sh
sudo bash install.sh
```

The installer will:
1. Update system packages
2. Install Node.js 20 LTS
3. Install npm dependencies
4. Build the production bundle
5. Configure Nginx as a reverse proxy
6. Enable and start Nginx

### Step 3 – Access the app
Open your browser to `http://YOUR_LXC_IP`

---

## Manual Installation (Step by Step)

```bash
# 1. Install Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs nginx

# 2. Navigate to project
cd /path/to/statsphere

# 3. Install dependencies
npm install

# 4. Build
npm run build
# Output goes to ./dist/

# 5. Configure Nginx (see install.sh for full config)
sudo nano /etc/nginx/sites-available/statsphere
# Paste the nginx config from install.sh

sudo ln -s /etc/nginx/sites-available/statsphere /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl restart nginx
```

---

## HTTPS / SSL (Production)

```bash
# Install Certbot
sudo apt-get install -y certbot python3-certbot-nginx

# Update your nginx config server_name with your actual domain first, then:
sudo certbot --nginx -d yourdomain.com

# Auto-renew
sudo systemctl enable certbot.timer
```

---

## Directory Structure

```
statsphere/
├── public/               # Static assets (icons, favicon)
├── src/
│   ├── components/       # Reusable components
│   │   ├── Nav.jsx       # Top + bottom navigation
│   │   ├── Avatar.jsx    # Profile avatar with initials fallback
│   │   ├── SportBadge.jsx
│   │   └── PWABanner.jsx # PWA install prompt
│   ├── data/
│   │   └── seedData.js   # 125 fake athletes + stat definitions
│   ├── hooks/
│   │   └── useStore.jsx  # Global state (localStorage)
│   ├── pages/
│   │   ├── Home.jsx      # Dashboard
│   │   ├── Leaders.jsx   # Stat leaders board
│   │   ├── Filter.jsx    # Advanced search
│   │   ├── Athletes.jsx  # Athlete list
│   │   ├── AthleteDetail.jsx
│   │   └── Register.jsx  # 4-step registration form
│   ├── App.jsx           # Routes
│   ├── main.jsx
│   └── index.css         # Global styles + design tokens
├── index.html
├── vite.config.js        # Build config + PWA plugin
├── package.json
└── install.sh            # Ubuntu auto-installer
```

---

## Adding More Sports

Edit `src/data/seedData.js`:

1. Add the sport to `SPORTS`:
```js
lacrosse: { id: 'lacrosse', name: 'Lacrosse', emoji: '🥍', color: '#facc15' },
```

2. Add stat definitions to `SPORT_STATS_DEFS`:
```js
lacrosse: [
  { key: 'position', label: 'Position', type: 'text' },
  { key: 'goals', label: 'Goals', type: 'number' },
  // ...
],
```

3. Add positions to the `positions` object in `Register.jsx`.

4. Optionally add seed data generation for the new sport in `seedData.js`.

---

## PWA Installation

### Android (Chrome)
- Visit the app in Chrome
- Tap the "Install" banner that appears, or tap ⋮ → "Add to Home Screen"

### iOS (Safari)
- Visit the app in Safari
- Tap Share → "Add to Home Screen"

### Desktop (Chrome/Edge)
- Click the install icon (⊕) in the address bar

---

## Data Storage

All athlete data is stored in **browser localStorage** under the key `statsphere_users_v1`. Data persists across page reloads but is per-device/per-browser.

To reset to seed data: open the browser console and run:
```js
localStorage.removeItem('statsphere_users_v1'); location.reload();
```

---

## Tech Stack

| Layer | Technology |
|---|---|
| Framework | React 18 |
| Routing | React Router v6 |
| Build | Vite 5 |
| PWA | vite-plugin-pwa + Workbox |
| Icons | Lucide React |
| Web Server | Nginx |
| Styling | Pure CSS (no Tailwind) |
| State | React Context + localStorage |
| Data | In-memory seed + localStorage |

---

## License
MIT