From 93720699263664d103bbd5818c1cf208527e1cb4 Mon Sep 17 00:00:00 2001 From: David Gwilliam Date: Fri, 27 Mar 2026 13:09:59 -0700 Subject: [PATCH] docs: Update README and TODO with project documentation --- README.md | 510 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ TODO.md | 45 +++-- 2 files changed, 536 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 40cfff2..574addc 100644 --- a/README.md +++ b/README.md @@ -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 +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[] +``` + +**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 ` +- 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 + +``` +: + +[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= +``` + +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) diff --git a/TODO.md b/TODO.md index 28b0c4d..81af1f2 100644 --- a/TODO.md +++ b/TODO.md @@ -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