step-competition/README.md

# Step Competition App

A modern, streamlined web application for hosting workplace step competitions with 48+ participants across multiple teams.

## Features

**3 Simple Tabs:**
1. **Log Your Steps** - Easy 2-step selection (team → name) + instant personal history view
2. **Team Standings** - Combined team and individual leaderboards
3. **Competition Stats** - Overall metrics and visual progress charts

**Key Capabilities:**
- CSV bulk import for quick setup (8 teams × 6 people = 48 participants)
- Team-first navigation makes finding your name fast
- Personal step history shown immediately after selecting your name
- Real-time leaderboards with gold/silver/bronze highlighting
- Visual charts showing team progress over time
- Mobile-friendly responsive design
- SQLite backend - no complex database setup

## Quick Start

### 1. Install and Start
```bash
cd /home/sascha/gitea/step-competition
npm install
npm start
```

### 2. Setup Teams & Participants

**Option A: CSV Import (Recommended for 48 people)**

1. Create a CSV file with 3 columns: `team_name`, `participant_name`, `email`
2. See `sample_import.csv` for reference format
3. Open the app and go to "Log Your Steps" tab
4. Scroll down to "Admin: Bulk Import" section
5. Select your CSV file and click "Import CSV"

Example CSV format:
```csv
team_name,participant_name,email
Team Alpha,Alice Johnson,alice@example.com
Team Alpha,Bob Smith,bob@example.com
Team Beta,Carol Williams,carol@example.com
```

**Option B: Use Sample Data**
```bash
node sample-data.js
```

### 3. Start Logging Steps

**For Participants:**
1. Open http://localhost:3060 (or your Tailscale URL)
2. Select your team from dropdown
3. Select your name from dropdown
4. See your personal stats and history on the right
5. Enter today's date and step count
6. Click "Submit Steps"

**For Viewing Results:**
- **Team Standings** tab: See which teams and individuals are winning
- **Competition Stats** tab: View overall progress and charts

## Accessing Remotely

The server listens on port 3060 and is accessible via:

**Via Tailscale:**
```bash
# Find your Tailscale IP
tailscale ip -4

# Share with participants
http://YOUR_TAILSCALE_IP:3060
```

**Via Local Network:**
```bash
# Find your local IP
hostname -I | awk '{print $1}'

# Share with participants
http://YOUR_LOCAL_IP:3060
```

## CSV Import Format

Your CSV must have these exact column headers:
- `team_name` - Name of the team
- `participant_name` - Person's full name
- `email` - Email address (optional, can be empty)

The import will:
- Create teams automatically if they don't exist
- Add participants to their teams
- Skip duplicates (same name + team)
- Report how many teams and participants were created

## Project Structure

```
step-competition/
├── src/
│   ├── server.js       # Express server and API endpoints
│   └── database.js     # SQLite database initialization
├── public/
│   ├── index.html      # 3-tab interface
│   ├── styles.css      # Responsive styling
│   └── app.js          # Frontend JavaScript
├── sample_import.csv   # Template for bulk import (8 teams, 48 people)
├── step_competition.db # SQLite database (auto-created)
└── README.md
```

## API Endpoints

### Teams & Participants
- `GET /api/teams` - Get all teams
- `POST /api/teams` - Create a team
- `GET /api/participants` - Get all participants
- `POST /api/participants` - Create a participant
- `POST /api/import/csv` - Bulk import from CSV
- `GET /api/participants/:id/history` - Get participant's step history

### Steps
- `POST /api/steps` - Submit or update steps
- `GET /api/steps/:participantId/:date` - Get steps for specific date

### Leaderboards
- `GET /api/leaderboard/individual` - Individual rankings
- `GET /api/leaderboard/team` - Team rankings
- `GET /api/progress/daily` - Daily progress data for charts

## Configuration

**Change Port:**
Edit `src/server.js` line 8:
```javascript
const PORT = process.env.PORT || 3060;
```

Or use environment variable:
```bash
PORT=8080 npm start
```

## Database Schema

### teams
- `id`, `name`, `created_at`

### participants
- `id`, `name`, `email`, `team_id`, `created_at`

### daily_steps
- `id`, `participant_id`, `date`, `steps`, `created_at`, `updated_at`
- Unique constraint on (participant_id, date)

## Tips for Running a Competition

1. **Pre-populate**: Use CSV import to set up all 48 participants before launch
2. **Test First**: Import sample_import.csv and test with a few entries
3. **Share URL**: Send the Tailscale or local network URL to all participants
4. **Daily Reminders**: Encourage participants to log steps daily
5. **Showcase Leaderboards**: Display the Team Standings tab on a monitor
6. **Backup Data**: Periodically copy `step_competition.db` file

## Troubleshooting

**CSV import fails:**
- Check that your CSV has the exact column headers: `team_name,participant_name,email`
- Make sure there are no extra spaces or special characters
- Verify the file is saved as CSV format, not Excel

**Can't find my name:**
- Make sure you select the correct team first
- Names are listed alphabetically within each team
- Check that your name was imported correctly

**Steps not saving:**
- Verify you selected both team and name
- Check that you entered a valid number for steps
- Make sure the date is in the correct format

**Port 3060 already in use:**
- Change the PORT in src/server.js to another number (e.g., 3070)
- Or stop the other service using that port

## Resetting the Competition

To start fresh:
```bash
rm step_competition.db
npm start
```

A new empty database will be created. You'll need to re-import your participants.

## Browser Compatibility

Works with all modern browsers:
- Chrome/Edge (recommended)
- Firefox
- Safari
- Mobile browsers (iOS/Android)

## License

ISC