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)

# 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)

# 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

# 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

apt-get install -y unzip
unzip statsphere.zip -d /opt/statsphere-src
cd /opt/statsphere-src

Step 2 – Run the installer

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)

# 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)

# 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:

lacrosse: { id: 'lacrosse', name: 'Lacrosse', emoji: '🥍', color: '#facc15' },

2. Add stat definitions to SPORT_STATS_DEFS:

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:

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