Initial commit of step-competition project
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
212
README.md
Normal file
212
README.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user