david/euchre_camp
Public Access
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity

docs: Update README and TODO with project documentation

Browse Source
This commit is contained in:
David Gwilliam
2026-03-27 13:09:59 -07:00
parent a077d9d881
commit 9372069926
2 changed files with 536 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+510
View File
@@ -1 +1,511 @@
# EuchreCamp
A comprehensive tournament management and partnership analytics system for the card game Euchre.
## Overview
EuchreCamp is a full-stack Ruby web application built with Hanami 2.1 that provides:
- **Tournament Management**: Create and manage round-robin, single elimination, double elimination, and Swiss-style tournaments
- **Partnership Analytics**: Track partnership performance, win rates, and Elo changes between players
- **Player Profiles**: Display individual player statistics and partnership breakdowns
- **Admin Dashboard**: Centralized management interface for tournaments, players, and matches
- **Authentication & Authorization**: Role-based access control with player, tournament_admin, and club_admin roles
## Quick Start
### Prerequisites
- Ruby 3.3.3 (managed by mise or rbenv)
- Node.js 22+ (for asset compilation)
- SQLite3
- Bundler
### Installation
1. **Clone the repository:**
```bash
git clone <repository-url>
cd euchre_camp
```
2. **Install dependencies:**
```bash
bundle install
npm install
```
3. **Set up the database:**
```bash
bundle exec rake db:migrate
```
4. **Compile assets:**
```bash
./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css
```
5. **Start the server:**
```bash
bundle exec puma -p 3000 -e development
```
### Accessing the Application
- **Main Page**: http://localhost:3000
- **Admin Dashboard**: http://localhost:3000/admin
- **Rankings**: http://localhost:3000/rankings
- **Login**: http://localhost:3000/login
## Development
### Project Structure
```
euchre_camp/
├── app/
│ ├── actions/ # Hanami actions (controllers)
│ ├── assets/ # CSS, JavaScript, images
│ ├── repositories/ # ROM repositories for data access
│ ├── services/ # Business logic (Elo calculator, partnership tracker)
│ ├── templates/ # ERB view templates
│ ├── views/ # Hanami view objects
│ └── action.rb # Base action class with auth helpers
├── config/
│ ├── routes.rb # Application routes
│ ├── app.rb # Hanami app configuration
│ └── assets.js # Asset compilation configuration
├── db/
│ ├── migrate/ # Database migrations
│ └── euchre_camp.db # SQLite database
├── lib/
│ └── euchre_camp/ # Domain models and entities
├── spec/
│ └── acceptance/ # RSpec acceptance tests
└── public/
└── assets/ # Compiled assets
```
### Running the Application
**Development mode (with auto-reload):**
```bash
bundle exec puma -p 3000 -e development
```
**Production mode:**
```bash
bundle exec puma -p 3000 -e production
```
### Database Management
**Run migrations:**
```bash
bundle exec rake db:migrate
```
**Rollback last migration:**
```bash
bundle exec rake db:migrate[<version>]
```
**Reset database:**
```bash
bundle exec rake db:reset
```
### Testing
**Run all acceptance tests:**
```bash
bundle exec rspec spec/acceptance/
```
**Run specific test:**
```bash
bundle exec rspec spec/acceptance/tournament_partnership_spec.rb:280
```
**Run with documentation:**
```bash
bundle exec rspec spec/acceptance/ --format documentation
```
### Assets
**Compile CSS for development:**
```bash
./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css
```
**Watch for changes (requires separate process):**
```bash
./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css --watch
```
## Features
### Tournament Management
#### Creating a Tournament
1. Navigate to Admin Dashboard (`/admin`)
2. Click "Create Tournament"
3. Enter tournament details:
- Name
- Format (round-robin, single elimination, double elimination, Swiss)
- Number of teams/players
4. Register participants
5. Generate schedule
6. Record match results
#### Tournament Formats
- **Round-Robin**: Each team plays every other team once
- **Single Elimination**: Lose once and you're out
- **Double Elimination**: Must lose twice to be eliminated
- **Swiss**: Pairings based on win-loss records
### Partnership Analytics
#### Tracking Partnerships
The system automatically tracks:
- Games played together
- Win/loss records
- Elo changes per partnership
- Partnership win rates
#### Viewing Partnership Data
1. Visit any player's profile page (`/players/:id/profile`)
2. Scroll to "Partnership Performance" section
3. View statistics for each partner
### Player Profiles
Each player profile displays:
- Current Elo rating
- Total games played
- Win rate
- Partnership statistics
- Recent games timeline
### Admin Dashboard
The admin dashboard provides:
- Quick statistics (total players, active tournaments, recent matches)
- Quick action buttons for common tasks
- Recent matches table
- Links to all admin sections
## Authentication & Authorization
### User Roles
| Role | Permissions |
|------|-------------|
| **Player** | Edit own profile, record own matches within 5 minutes |
| **Tournament Admin** | Create/manage tournaments, edit matches in their tournaments (no time limit) |
| **Club Admin** | Full access to edit/delete any record, manage all players and tournaments |
### Login/Logout
**Login:**
- Navigate to `/login`
- Enter email and password
- Click "Login"
**Logout:**
- Click "Logout" in navigation bar
### Registration
Currently registration is not implemented. To add a user manually:
1. Access the database: `sqlite3 db/euchre_camp.db`
2. Insert a user record:
```sql
INSERT INTO users (player_id, email, password_digest, role, created_at, updated_at)
VALUES (1, 'user@example.com', '$2b$12$...', 'club_admin', datetime('now'), datetime('now'));
```
(Use BCrypt to generate password hash)
## API Reference
### Routes
#### Public Routes
- `GET /` - Redirects to rankings
- `GET /rankings` - Player rankings
- `GET /players/:id` - Player profile
- `GET /players/:id/profile` - Player profile with partnerships
- `GET /players/:id/schedule` - Player tournament schedule
#### Authentication Routes
- `GET /login` - Login form
- `POST /auth/login` - Process login
- `GET /logout` - Logout and clear session
#### Admin Routes (Require Authentication)
- `GET /admin` - Admin dashboard
- `GET /admin/players` - List all players
- `GET /admin/players/new` - Add new player form
- `POST /admin/players` - Create new player
- `GET /admin/players/:id/edit` - Edit player form
- `PATCH /admin/players/:id` - Update player
- `DELETE /admin/players/:id` - Delete player
- `GET /admin/matches` - List all matches
- `GET /admin/matches/new` - Record match form
- `POST /admin/matches` - Create match
- `GET /admin/matches/:id/edit` - Edit match form
- `PATCH /admin/matches/:id` - Update match
- `GET /admin/matches/upload` - CSV upload form
- `POST /admin/matches/process_upload` - Process CSV upload
- `GET /admin/tournaments` - List all tournaments
- `GET /admin/tournaments/new` - Create tournament form
- `POST /admin/tournaments` - Create tournament
- `GET /admin/tournaments/:id` - Tournament details
- `GET /admin/tournaments/:id/edit` - Edit tournament form
- `PATCH /admin/tournaments/:id` - Update tournament
- `DELETE /admin/tournaments/:id` - Delete tournament
- `POST /admin/tournaments/:id/participants` - Add participant
- `DELETE /admin/tournaments/:id/participants/:player_id` - Remove participant
- `POST /admin/tournaments/:id/teams` - Create team
- `GET /admin/tournaments/:id/teams/:team_id/edit` - Edit team form
- `PATCH /admin/tournaments/:id/teams/:team_id` - Update team
- `DELETE /admin/tournaments/:id/teams/:team_id` - Delete team
- `POST /admin/tournaments/:id/schedule` - Generate schedule
- `GET /admin/tournaments/:id/rounds/:round_id` - View round matchups
- `GET /admin/tournaments/:id/results` - Tournament results
- `POST /admin/tournaments/:id/results` - Save results
- `POST /admin/tournaments/:id/complete` - Complete tournament
## Database Schema
### Tables
- **players**: Player information and ratings
- **users**: Authentication and authorization
- **events**: Tournaments and events
- **event_participants**: Player participation in tournaments
- **teams**: Teams in tournaments
- **tournament_rounds**: Tournament rounds
- **bracket_matchups**: Matchups per round
- **matches**: Individual match results
- **elo_snapshots**: Elo rating history
- **partnership_games**: Partnership occurrence tracking
- **partnership_stats**: Aggregated partnership statistics
## Common Tasks
### Adding a New Player
1. Navigate to Admin Dashboard
2. Click "Add Player"
3. Enter name and initial rating (default 1000)
4. Click "Create Player"
### Recording a Match
1. Navigate to Admin Dashboard
2. Click "Record Match Result"
3. Select players for Team 1 and Team 2
4. Enter scores
5. Click "Create Match"
### Creating a Tournament
1. Navigate to Admin Dashboard
2. Click "Create Tournament"
3. Enter tournament details
4. Register participants
5. Generate schedule
6. Start recording results
### Editing a Match
**Within 5 minutes (any user):**
1. Navigate to `/admin/matches`
2. Click "Edit" next to the match
3. Update scores
4. Click "Update Match"
**Anytime (tournament admin or club admin):**
- Same process as above, no time restriction
## Troubleshooting
### Common Issues
**Server won't start:**
- Check if port 3000 is already in use: `lsof -i :3000`
- Kill existing process: `kill -9 <PID>`
- Try a different port: `bundle exec puma -p 3001`
**CSS not loading:**
- Recompile assets: `./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css`
- Clear browser cache
**Database errors:**
- Run migrations: `bundle exec rake db:migrate`
- Reset database: `bundle exec rake db:reset`
**Authorization errors:**
- Ensure you're logged in
- Check user role in database
### Debugging
**Check server logs:**
```bash
tail -f /tmp/puma.log
```
**Check database:**
```bash
sqlite3 db/euchre_camp.db
sqlite> .tables
sqlite> SELECT * FROM users;
```
## Development Workflow
### Making Changes
1. Create a feature branch: `git checkout -b feature/your-feature`
2. Make changes to code
3. Run tests: `bundle exec rspec spec/acceptance/`
4. Commit with conventional commit message
5. Push to remote: `git push origin feature/your-feature`
6. Create pull request
### Commit Message Format
```
<type>: <description>
[optional body]
[optional footer]
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes
- `refactor`: Code refactoring
- `test`: Test changes
- `chore`: Build/dependency changes
### Code Style
- Follow existing code patterns in the project
- Use ROM (Ruby Object Mapper) for database access
- Keep business logic in services
- Use dependency injection in actions
- Write acceptance tests for new features
## Deployment
### Production Environment
1. **Set production environment variables:**
```bash
export HANAMI_ENV=production
export DATABASE_URL=sqlite:///path/to/prod.db
export SESSION_SECRET=<secure-random-string>
```
2. **Compile assets for production:**
```bash
./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css
```
3. **Run migrations:**
```bash
bundle exec rake db:migrate
```
4. **Start server:**
```bash
bundle exec puma -p 3000 -e production
```
### Using a Process Manager
**Using systemd:**
```ini
[Unit]
Description=EuchreCamp
After=network.target
[Service]
Type=simple
User=deploy
WorkingDirectory=/var/www/euchre_camp
Environment=HANAMI_ENV=production
ExecStart=/usr/local/bin/bundle exec puma -C config/puma.rb
Restart=always
[Install]
WantedBy=multi-user.target
```
**Using PM2 (Node.js):**
```bash
pm2 start bundle exec -- puma -C config/puma.rb
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests to ensure they pass
5. Submit a pull request
## License
MIT License - see LICENSE file for details
## Credits
Built with:
- Hanami 2.1
- ROM (Ruby Object Mapper)
- SQLite3
- RSpec
- Puma
## Additional Resources
- [Hanami Documentation](https://guides.hanamirb.org/)
- [ROM Documentation](https://rom-rb.org/)
- [RSpec Documentation](https://rspec.info/)
- [Euchre Rules](https://www.pagat.com/euchre/euchre.html)
TODO.md
+26 -19
View File
@@ -58,12 +58,13 @@
- [ ] Bracket visualization
### Implementation Phases
- [ ] Phase 1: Navigation & Layout (Week 1)
- [ ] Phase 2: Player Profile Enhancements (Week 1-2)
- [ ] Phase 3: Tournament Admin View (Week 2-3)
- [ ] Phase 4: Club Admin View (Week 3-4)
- [ ] Phase 5: Player Schedule View (Week 4)
- [ ] Phase 6: Polish & Testing (Week 5)
- [x] Phase 1: Navigation & Layout (Week 1)
- [x] Phase 2: Player Profile Enhancements (Week 1-2)
- [x] Phase 3: Tournament Admin View (Week 2-3)
- [x] Phase 4: Club Admin View (Week 3-4)
- [x] Phase 5: Player Schedule View (Week 4)
- [ ] Phase 6: Authentication & Authorization (Week 5)
- [ ] Phase 7: Polish & Testing (Week 6)
## Future Enhancements
@@ -84,28 +85,34 @@
## AAA System (Authentication, Authorization, Accounting)
### Authentication
- [x] Create users table migration (db/migrate/20240915000008_create_users.rb)
- [x] Create users repository (app/repositories/users.rb)
- [x] Create users model/struct (lib/euchre_camp/entities/user.rb)
- [x] Build login page template (app/templates/auth/login.html.erb)
- [x] Build login action (app/actions/auth/login.rb)
- [x] Build logout action (app/actions/auth/logout.rb)
- [x] Create users table migration
- [x] Create users repository
- [x] Create users model/struct
- [x] Build login page template
- [x] Build login action
- [x] Build logout action
- [x] Add login/logout routes
- [x] Add BCrypt to Gemfile
- [x] Install BCrypt (bundle install)
- [x] Update base Action with authentication helpers
- [x] Add current_player to views
- [x] Install BCrypt
- [x] Create authorization service
- [x] Add authorization helpers to base action
- [x] Add role-based access control
- [ ] Create registration action and template
- [ ] Add session management middleware
- [ ] Add current_user helper to views
- [ ] Password reset functionality
- [ ] Email confirmation system
### Authorization
- [ ] Define roles (player, tournament_admin, club_admin, system_admin)
- [ ] Implement RBAC middleware
- [x] Define roles (player, tournament_admin, club_admin, system_admin)
- [x] Create Authorization service
- [x] Implement permission checks
- [x] Add authorization to admin dashboard
- [x] Add authorization to player management
- [x] Add authorization to tournament management
- [x] Add 5-minute match edit window
- [ ] Add role assignment UI
- [ ] Protect routes based on permissions
- [ ] Permission checks in actions
- [ ] Add permission checks to all routes
### Accounting
- [ ] Create activity logging system