2026-03-30 02:30:16 +00:00
4 changed files with 1056 additions and 0 deletions
@@ -0,0 +1,283 @@
+# Authentication, Authorization, and Accounting (AAA) Design
+
+## Overview
+Implement a comprehensive AAA system for EuchreCamp with user authentication, role-based authorization, and activity logging.
+
+## Authentication (Who are you?)
+
+### User Model
+```ruby
+# Database Schema
+table :users do
+  primary_key :id
+  foreign_key :player_id, :players  # Links to existing player record
+  column :email, String, null: false, unique: true
+  column :password_digest, String, null: false
+  column :confirmed, Boolean, default: false
+  column :confirmation_token, String
+  column :confirmation_sent_at, DateTime
+  column :reset_password_token, String
+  column :reset_password_sent_at, DateTime
+  column :failed_login_attempts, Integer, default: 0
+  column :locked_until, DateTime
+  column :last_login_at, DateTime
+  column :last_login_ip, String
+  column :created_at, DateTime, null: false
+  column :updated_at, DateTime, null: false
+end
+
+# Indexes
+add_index :users, :email, unique: true
+add_index :users, :confirmation_token
+add_index :users, :reset_password_token
+```
+
+### Authentication Flow
+1. User enters email and password
+2. System verifies email exists and account is not locked
+3. BCrypt verifies password hash
+4. If successful:
+   - Update `last_login_at` and `last_login_ip`
+   - Reset `failed_login_attempts`
+   - Create session/token
+5. If failed:
+   - Increment `failed_login_attempts`
+   - Lock account after 5 failed attempts (15 minutes)
+
+### Session Management
+- Use signed cookies for session storage
+- Session expires after 30 days of inactivity
+- Session invalidation on password change
+- Concurrent session limits (optional)
+
+### Password Requirements
+- Minimum 8 characters
+- At least one uppercase letter
+- At least one lowercase letter
+- At least one number
+- At least one special character
+
+### Registration Flow
+1. User registers with email and password
+2. System creates user record with `confirmed: false`
+3. Send confirmation email with unique token
+4. User clicks link to confirm account
+5. Account activated and ready for login
+
+### Password Reset Flow
+1. User requests password reset
+2. System generates unique token (expires in 1 hour)
+3. Send reset email with token link
+4. User enters new password
+5. System validates and updates password hash
+6. Invalidate all existing sessions
+
+## Authorization (What can you do?)
+
+### Role-Based Access Control (RBAC)
+
+#### Roles
+```ruby
+ROLES = {
+  player: 0,      # Default user - can view rankings, own profile
+  tournament_admin: 1,  # Can manage specific tournaments
+  club_admin: 2,        # Superuser - full access
+  system_admin: 3       # Technical admin access
+}
+```
+
+#### Permission Matrix
+
+| Permission | Player | Tournament Admin | Club Admin | System Admin |
+|------------|--------|------------------|------------|--------------|
+| View rankings | ✅ | ✅ | ✅ | ✅ |
+| View own profile | ✅ | ✅ | ✅ | ✅ |
+| Edit own profile | ✅ | ✅ | ✅ | ✅ |
+| View other profiles | ✅ | ✅ | ✅ | ✅ |
+| Record own matches | ✅ | ✅ | ✅ | ✅ |
+| Create tournaments | ❌ | ✅ | ✅ | ✅ |
+| Manage own tournaments | ❌ | ✅ | ✅ | ✅ |
+| Manage all tournaments | ❌ | ❌ | ✅ | ✅ |
+| Manage all players | ❌ | ❌ | ✅ | ✅ |
+| Club settings | ❌ | ❌ | ✅ | ✅ |
+| System settings | ❌ | ❌ | ❌ | ✅ |
+
+### Implementation
+```ruby
+module EuchreCamp
+  module Auth
+    class Authorization
+      def self.can?(user, action, resource = nil)
+        case action
+        when :view_rankings
+          true  # All users can view rankings
+        when :edit_profile
+          resource.nil? || resource.id == user.player_id
+        when :create_tournament
+          user.club_admin? || user.system_admin?
+        when :manage_tournament
+          user.club_admin? || user.system_admin? || 
+          (user.tournament_admin? && resource.admin_id == user.player_id)
+        when :manage_players
+          user.club_admin? || user.system_admin?
+        else
+          false
+        end
+      end
+    end
+  end
+end
+```
+
+### Middleware
+- Authentication middleware checks for valid session
+- Authorization middleware verifies permissions
+- Redirect unauthenticated users to login
+- Show 403 Forbidden for unauthorized actions
+
+## Accounting (What did you do?)
+
+### Activity Logging
+```ruby
+table :activity_logs do
+  primary_key :id
+  foreign_key :user_id, :users
+  column :action, String, null: false  # e.g., 'login', 'create_tournament', 'record_match'
+  column :resource_type, String        # e.g., 'tournament', 'match', 'player'
+  column :resource_id, Integer
+  column :ip_address, String
+  column :user_agent, String
+  column :details, JSON                # Additional context
+  column :created_at, DateTime, null: false
+end
+
+add_index :activity_logs, [:user_id, :created_at]
+add_index :activity_logs, [:resource_type, :resource_id]
+```
+
+### Tracked Events
+- Authentication events (login, logout, password change)
+- Tournament management (create, update, delete, schedule)
+- Match recording (create, update, delete)
+- Player management (create, update)
+- Settings changes
+
+### Audit Reports
+- User activity timeline
+- Tournament lifecycle audit
+- Match result verification log
+- System changes overview
+
+## Implementation Plan
+
+### Phase 1: Authentication (Week 1-2)
+- [ ] Create users table and model
+- [ ] Implement BCrypt password hashing
+- [ ] Build login/logout actions
+- [ ] Create registration flow
+- [ ] Add session management
+- [ ] Password reset functionality
+
+### Phase 2: Authorization (Week 2-3)
+- [ ] Define roles and permissions
+- [ ] Implement RBAC middleware
+- [ ] Add role assignment UI (for club admins)
+- [ ] Protect routes based on roles
+- [ ] Add permission checks to actions
+
+### Phase 3: Accounting (Week 3-4)
+- [ ] Create activity logging system
+- [ ] Track key events
+- [ ] Build audit reports UI
+- [ ] Add activity feed to dashboard
+
+### Phase 4: Security Hardening (Week 4-5)
+- [ ] Rate limiting on login attempts
+- [ ] IP-based lockout
+- [ ] Secure cookie settings
+- [ ] CSRF protection
+- [ ] Security headers
+- [ ] Session fixation prevention
+
+## Security Considerations
+
+### Password Security
+- Use BCrypt with cost factor 12+
+- Never store plaintext passwords
+- Enforce strong password policy
+- Rate limit password attempts
+
+### Session Security
+- Use signed, encrypted cookies
+- Regenerate session ID on privilege escalation
+- Set appropriate expiration times
+- Invalidate on password change
+
+### Access Control
+- Principle of least privilege
+- Defense in depth
+- Fail securely (deny by default)
+- Log all access attempts
+
+### Data Protection
+- Encrypt sensitive data at rest
+- Secure transmission (HTTPS only)
+- Regular security audits
+- Compliance with privacy regulations
+
+## API Endpoints
+
+### Authentication
+```
+POST /auth/login       # Login with email/password
+POST /auth/logout      # Logout current session
+POST /auth/register    # Create new account
+POST /auth/confirm     # Confirm email address
+POST /auth/forgot      # Request password reset
+POST /auth/reset       # Reset password with token
+```
+
+### Users
+```
+GET  /users/me         # Get current user profile
+PATCH /users/me        # Update own profile
+GET  /users/:id        # Get user profile (public)
+```
+
+### Admin
+```
+GET  /admin/users      # List users (club admin only)
+PATCH /admin/users/:id # Update user roles (club admin only)
+GET  /admin/activity   # View audit logs (club admin only)
+```
+
+## Testing Strategy
+
+### Unit Tests
+- Password hashing verification
+- Permission calculations
+- Session management
+- Activity logging
+
+### Integration Tests
+- Login/logout flow
+- Registration process
+- Password reset
+- Role-based access
+
+### Security Tests
+- SQL injection prevention
+- XSS prevention
+- CSRF protection
+- Rate limiting
+- Session security
+
+## Migration Steps
+
+1. Create users table and related migrations
+2. Add foreign key from users to players
+3. Migrate existing player data to users (optional)
+4. Update navigation to show login/logout links
+5. Add authentication checks to existing actions
+6. Implement role assignment for existing admins
+7. Set up activity logging for new features
@@ -0,0 +1,88 @@
+# AAA System Implementation Progress
+
+## Files Created
+
+### Database
+- `db/migrate/20240915000008_create_users.rb` - Users table with authentication fields
+
+### Models/Entities
+- `lib/euchre_camp/entities/user.rb` - User entity with authentication methods
+
+### Repositories
+- `app/repositories/users.rb` - Users repository with authentication logic
+
+### Actions
+- `app/actions/auth/login.rb` - Login form and authentication processing
+- `app/actions/auth/logout.rb` - Logout action
+
+### Templates
+- `app/templates/auth/login.html.erb` - Login page template
+
+### Routes
+- Updated `config/routes.rb` with login/logout routes
+
+### Styles
+- Updated `app/assets/css/app.css` with auth page styling
+
+### Documentation
+- `AAA_DESIGN.md` - Complete AAA design specification
+- `AAA_IMPLEMENTATION.md` - This file
+
+## Implementation Checklist
+
+### Authentication
+- [x] Users table migration created
+- [x] Users repository with authentication methods
+- [x] User entity/model with authentication helpers
+- [x] Login form template
+- [x] Login action (GET and POST)
+- [x] Logout action
+- [x] Login/logout routes
+- [ ] BCrypt added to Gemfile (pending bundle install)
+- [ ] Session management middleware
+- [ ] Current user helper for views
+- [ ] Registration flow
+- [ ] Password reset functionality
+- [ ] Email confirmation system
+
+### Authorization
+- [ ] Role definitions (player, tournament_admin, club_admin, system_admin)
+- [ ] Permission matrix implementation
+- [ ] RBAC middleware
+- [ ] Role assignment UI
+- [ ] Route protection
+
+### Accounting
+- [ ] Activity logging system
+- [ ] Audit report UI
+- [ ] Activity feed
+
+## Next Steps
+
+1. Install BCrypt: `bundle install`
+2. Create registration action and template
+3. Implement session management middleware
+4. Add current_user helper to base action
+5. Create password reset flow
+6. Build email confirmation system
+7. Implement role-based authorization
+8. Add activity logging
+
+## Security Features Implemented
+
+### Account Lockout
+- After 5 failed login attempts, account is locked for 15 minutes
+- Prevents brute force attacks
+
+### Password Storage
+- Passwords will be hashed with BCrypt
+- Never stored in plaintext
+
+### Session Security
+- Session cleared on logout
+- User ID and player ID stored in session
+
+### Input Validation
+- Email format validation
+- Password required
+- Form submission protection
@@ -0,0 +1,135 @@
+# EuchreCamp - Project Todo List
+
+## Completed Features
+
+### Backend
+- [x] Database schema for matches, players, teams, events
+- [x] Elo rating calculator and job
+- [x] Partnership tracking and analytics
+- [x] Tournament generator (round-robin, single elim, double elim, Swiss)
+- [x] ROM relations and repositories
+- [x] Acceptance test suite (8 tests passing)
+
+### Frontend
+- [x] Basic player rankings page
+- [x] Match entry form
+
+## In Progress - UI Development
+
+### Completed
+- [x] Navigation layout (app.html.erb)
+- [x] UI Design document (UI_DESIGN.md)
+- [x] Player Profile template (existing)
+- [x] Basic CSS styling
+- [x] Player Schedule view (action + template)
+- [x] Route for player schedule
+
+### View Types to Implement
+- [ ] Tournament Admin View (Phase 2-3)
+  - Create/manage tournaments
+  - Set up brackets and matchups
+  - Record match results
+  - View tournament standings
+
+- [ ] Club Admin View (Superuser) (Phase 3-4)
+  - Manage all players
+  - View club-wide statistics
+  - Configure club settings
+  - Manage tournaments
+
+- [ ] Player Profile View (Phase 1-2)
+  - Display player info and Elo rating
+  - Show partnership analytics
+  - Display match history
+  - Tournament participation
+  - Enhance existing template
+
+- [ ] Player Tournament Schedule View (Phase 4)
+  - Show upcoming matches
+  - Display tournament brackets
+  - Record personal match results
+
+### UI Components Needed
+- [x] Navigation system (role-based) - Started
+- [ ] Dashboard layouts
+- [ ] Forms for data entry
+- [ ] Tables for displaying data
+- [ ] Charts for statistics
+- [ ] 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)
+
+## Future Enhancements
+
+### Features
+- [ ] Real-time match updates
+- [ ] Mobile-responsive design
+- [ ] Email notifications
+- [ ] Import/Export functionality
+- [ ] API for third-party integrations
+- [ ] Login/AAA System (Authentication, Authorization, Accounting)
+
+### Technical
+- [ ] Performance optimization
+- [ ] Caching strategy
+- [ ] Security hardening
+- [ ] Deployment pipeline
+
+## 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] 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
+- [ ] Create registration action and template
+- [ ] Add session management middleware
+- [ ] Password reset functionality
+- [ ] Email confirmation system
+
+### Authorization
+- [ ] Define roles (player, tournament_admin, club_admin, system_admin)
+- [ ] Implement RBAC middleware
+- [ ] Add role assignment UI
+- [ ] Protect routes based on permissions
+- [ ] Permission checks in actions
+
+### Accounting
+- [ ] Create activity logging system
+- [ ] Track authentication events
+- [ ] Track tournament management events
+- [ ] Track match recording events
+- [ ] Build audit reports UI
+
+### Security
+- [ ] Rate limiting on login attempts
+- [ ] IP-based lockout (partially implemented in users repo)
+- [ ] Secure cookie settings
+- [ ] CSRF protection
+- [ ] Security headers
+- [ ] Session fixation prevention
+
+## Known Issues
+- [ ] Database IDs not resetting between tests (workaround: query by round_number)
+- [ ] Need to clean up debug output from acceptance tests
+- [ ] README is minimal and needs expansion
+
+## Next Steps
+1. Design UI mockups for each view type
+2. Implement navigation system
+3. Build out Tournament Admin view
+4. Add role-based access control
+5. Create reusable UI components
@@ -0,0 +1,550 @@
+# EuchreCamp UI Design
+
+## Overview
+Design for four distinct user views with role-based access control:
+1. Tournament Admin View
+2. Club Admin View (Superuser)
+3. Player Profile View
+4. Player Tournament Schedule View
+
+## Layout Structure
+
+### Navigation Bar (All Views)
+```html
+<nav class="main-nav">
+  <div class="nav-brand">
+    <a href="/">EuchreCamp</a>
+  </div>
+  <div class="nav-links">
+    <a href="/rankings">Rankings</a>
+    <% if defined?(current_player) && current_player %>
+      <a href="/players/<%= current_player.id %>/profile">My Profile</a>
+      <a href="/players/<%= current_player.id %>/schedule">My Schedule</a>
+      <% if current_player.admin? %>
+        <a href="/admin">Admin</a>
+      <% end %>
+    <% end %>
+  </div>
+  <div class="nav-user">
+    <% if defined?(current_player) && current_player %>
+      <span><%= current_player.name %></span>
+      <a href="/logout">Logout</a>
+    <% else %>
+      <a href="/login">Login</a>
+      <a href="/register">Register</a>
+    <% end %>
+  </div>
+</nav>
+```
+
+## Authentication Views
+
+### Login Page
+**URL:** `/login`  
+**Purpose:** Allow existing users to sign in
+
+#### Layout:
+```
+-------------------------------------------+
+|  EuchreCamp - Login                       |
+-------------------------------------------+
+|                                           |
+|  [Logo/Brand]                             |
+|                                           |
+|  Email:    [_______________________]      |
+|  Password: [_______________________]      |
+|  [ ] Remember me                          |
+|                                           |
+|  [Login]                                  |
+|                                           |
+|  Don't have an account?                   |
+|  [Register here]                          |
+|                                           |
+|  Forgot password?                         |
+|  [Reset password]                         |
+-------------------------------------------+
+```
+
+### Registration Page
+**URL:** `/register`  
+**Purpose:** Allow new users to create accounts
+
+#### Layout:
+```
+-------------------------------------------+
+|  EuchreCamp - Create Account              |
+-------------------------------------------+
+|                                           |
+|  Join EuchreCamp to track your games      |
+|  and partnerships!                        |
+|                                           |
+|  Full Name:    [_______________________]  |
+|  Email:        [_______________________]  |
+|  Password:     [_______________________]  |
+|  Confirm:      [_______________________]  |
+|                                           |
+|  [Create Account]                         |
+|                                           |
+|  Already have an account?                 |
+|  [Login here]                             |
+-------------------------------------------+
+```
+
+### Password Reset Page
+**URL:** `/password/reset`  
+**Purpose:** Allow users to reset forgotten passwords
+
+#### Layout:
+```
+-------------------------------------------+
+|  Reset Password                           |
+-------------------------------------------+
+|                                           |
+|  Enter your email address and we'll       |
+|  send you a reset link.                   |
+|                                           |
+|  Email: [___________________________]     |
+|                                           |
+|  [Send Reset Link]                        |
+|                                           |
+|  Remember your password?                  |
+|  [Login here]                             |
+-------------------------------------------+
+```
+
+### Email Confirmation Page
+**URL:** `/confirm`  
+**Purpose:** Display confirmation status
+
+#### Layout:
+```
+-------------------------------------------+
+|  Email Confirmation                       |
+-------------------------------------------+
+|                                           |
+|  ✓ Email Confirmed!                       |
+|  Your account is now active.              |
+|                                           |
+|  [Go to Dashboard]                        |
+|                                           |
+|  OR                                       |
+|                                           |
+|  ✗ Confirmation Failed                    |
+|  The link has expired or is invalid.      |
+|                                           |
+|  [Request new confirmation]               |
+-------------------------------------------+
+```
+
+## 1. Tournament Admin View
+
+### URL: `/admin/tournaments`
+
+**Purpose**: Create, manage, and monitor tournaments
+
+### Components:
+
+#### Dashboard
+- **Upcoming Tournaments Table**
+  - Name, Date, Format, Status, Actions (View/Edit/Manage)
+  - Quick action buttons: Schedule, Add Teams, Record Results
+
+#### Tournament Detail Page
+- **Tournament Info Header**
+  - Name, Format, Status, Dates
+  - Quick stats: Teams, Rounds, Matches, Participants
+
+- **Tournament Management Tabs**
+  ```
+  Overview | Participants | Teams | Schedule | Results | Analytics
+  ```
+
+- **Overview Tab**
+  - Current standings
+  - Next matches
+  - Tournament progress bar
+
+- **Participants Tab**
+  - List of registered players
+  - Add/Remove participants
+  - Bulk import from CSV
+
+- **Teams Tab**
+  - Team management (create/edit/delete teams)
+  - Assign players to teams
+  - Team standings
+
+- **Schedule Tab**
+  - Generate round-robin schedule
+  - Generate bracket (single/double elim)
+  - View round matchups
+  - Re-schedule matches
+
+- **Results Tab**
+  - Match result entry form
+  - CSV upload for batch results
+  - Verify and submit results
+
+- **Analytics Tab**
+  - Tournament statistics
+  - Partnership performance
+  - Elo changes
+
+### Wireframe Layout:
+```
+-------------------------------------------+
+|  Tournament Admin                         |
+|  [Create New] [Generate Schedule]         |
+-------------------------------------------+
+|  Active: Spring Championship (Round 3/5)  |
+|  [Overview] [Teams] [Schedule] [Results]  |
+-------------------------------------------+
+|  Match Schedule - Round 3                 |
+|  ---------------------------------------  |
+|  Match 1: Team A vs Team B [Enter Result] |
+|  Match 2: Team C vs Team D [Enter Result] |
+|  Match 3: Team E vs Team F [Enter Result] |
+-------------------------------------------+
+```
+
+## 2. Club Admin View (Superuser)
+
+### URL: `/admin` or `/admin/club`
+
+**Purpose**: Club-wide management and oversight
+
+### Components:
+
+#### Club Dashboard
+- **Quick Stats Overview**
+  - Total Players
+  - Active Tournaments
+  - Matches This Week
+  - Average Elo Rating
+
+- **Recent Activity Feed**
+  - New player registrations
+  - Tournament creations
+  - Match results
+  - Partnership records
+
+#### Player Management
+- **Player Directory**
+  - Searchable list of all players
+  - Filter by status, rating range, activity
+  - Bulk actions: Email, Export, Update ratings
+
+- **Player Editor**
+  - Edit player details
+  - View player history
+  - Manage player status
+
+#### Tournament Management
+- **All Tournaments List**
+  - Filter by status, format, date range
+  - Archive/completed tournaments
+  - Clone existing tournaments
+
+#### Club Settings
+- **Configuration**
+  - Default tournament settings
+  - Elo rating parameters
+  - Partnership tracking preferences
+  - Notification settings
+
+#### Analytics & Reports
+- **Club Statistics**
+  - Rating distribution charts
+  - Activity heatmaps
+  - Partnership network graph
+  - Export reports (PDF/CSV)
+
+### Wireframe Layout:
+```
+-------------------------------------------+
+|  Club Admin Dashboard                     |
+|  [Players] [Tournaments] [Reports] [Settings]
+-------------------------------------------+
+|  Quick Stats: 45 Players | 3 Tournaments  |
+-------------------------------------------+
+|  Recent Activity                          |
+|  - John joined the club                   |
+|  - Spring Championship started            |
+|  - Emma & Alice won match vs Bob & Charlie|
+-------------------------------------------+
+|  Player Directory                         |
+|  [Search] [Filter by Rating] [Export]     |
+|  ---------------------------------------  |
+|  Rank | Name      | Elo   | Status        |
+|  1    | Emma      | 1200  | Active        |
+|  2    | Alice     | 1150  | Active        |
+-------------------------------------------+
+```
+
+## 3. Player Profile View
+
+### URL: `/players/:id/profile`
+
+**Purpose**: Display player information and partnership analytics
+
+### Components:
+
+#### Profile Header
+- Player name and avatar
+- Current Elo rating (with trend indicator)
+- Club affiliation
+- Member since date
+
+#### Statistics Grid
+```
+------------------+------------------+------------------+
+| Current Elo      | Total Games      | Win Rate         |
+| 1,200            | 45               | 58.2%            |
+------------------+------------------+------------------+
+| Partnership Elo  | Best Partnership | Games with Best  |
+| +150             | Alice (65%)      | 12 games         |
+------------------+------------------+------------------+
+```
+
+#### Partnership Performance Table
+- Partner name (clickable link)
+- Games played together
+- Win rate with confidence indicator
+- Total Elo change
+- Average Elo change per match
+- Last played together
+
+#### Recent Games Timeline
+- Chronological list of recent matches
+- Shows teams, scores, and result
+- Partner information for each game
+
+#### Tournament History
+- List of tournaments participated in
+- Final standings
+- Performance summary
+
+### Wireframe Layout:
+```
+-------------------------------------------+
+|  Player Profile: Emma                     |
+|  ELO: 1200 (+25 this week)                |
+-------------------------------------------+
+|  Partnership Performance                  |
+|  ---------------------------------------  |
+|  Partner    Games  Win Rate  ELO Change   |
+|  Alice      12     65%       +45          |
+|  Bob        8      50%       -20          |
+|  Charlie    5      60%       +30          |
+-------------------------------------------+
+|  Recent Games                             |
+|  ---------------------------------------  |
+|  2024-03-27  Win vs Bob+Charlie 10-7      |
+|  Partner: Alice                           |
+-------------------------------------------+
+```
+
+## 4. Player Tournament Schedule View
+
+### URL: `/players/:id/schedule`
+
+**Purpose**: View upcoming matches and tournament brackets
+
+### Components:
+
+#### Upcoming Matches
+- **This Week**
+  - Match date/time
+  - Opponent team
+  - Tournament name
+  - Location/notes
+  - Action: Record Result (if applicable)
+
+- **Next 30 Days**
+  - Calendar view of upcoming matches
+  - Grouped by tournament
+
+#### Active Tournaments
+- **My Tournaments List**
+  - Tournament name and status
+  - Current round
+  - My team's position
+  - Next match details
+
+- **Tournament Bracket View**
+  - Visual bracket display
+  - My team highlighted
+  - Progress tracking
+
+#### Match History
+- **Past Matches**
+  - Results from previous tournaments
+  - Performance trends
+
+### Wireframe Layout:
+```
+-------------------------------------------+
+|  Emma's Schedule                          |
+-------------------------------------------+
+|  This Week                                |
+|  ---------------------------------------  |
+|  Mar 28  Spring Championship              |
+|  vs Team B (Bob + Charlie)                |
+|  Court 3, 7:00 PM                         |
+|  [Record Result]                          |
+-------------------------------------------+
+|  Upcoming Matches                         |
+|  [Calendar View] [List View]              |
+|  ---------------------------------------  |
+|  Apr 1  Tournament X - Round 2            |
+|  Apr 5  Tournament Y - Quarterfinal       |
+|  Apr 8  Tournament X - Round 3            |
+-------------------------------------------+
+|  Active Tournaments                       |
+|  ---------------------------------------  |
+|  Spring Championship                      |
+|  Round 3 of 5 | Position: 2nd             |
+|  Next: vs Team C (Apr 1)                  |
+-------------------------------------------+
+```
+
+## Role-Based Access Control
+
+### Player Role (Default)
+- View own profile and schedule
+- View rankings and other player profiles
+- Record own match results (with verification)
+
+### Tournament Admin Role
+- All Player role permissions
+- Create and manage tournaments they admin
+- Add/remove participants
+- Record match results
+- View tournament analytics
+
+### Club Admin Role (Superuser)
+- All Tournament Admin permissions
+- Manage all players
+- Manage all tournaments
+- View club-wide analytics
+- Configure club settings
+- Export reports
+
+## UI Components to Build
+
+### 1. Navigation
+- Main navigation bar
+- Breadcrumb navigation
+- Tab navigation for multi-view pages
+
+### 2. Data Display
+- Data tables with sorting/filtering
+- Statistics cards
+- Charts (using Chart.js or similar)
+- Calendar views
+
+### 3. Forms
+- Player registration/edit forms
+- Tournament creation/edit forms
+- Match result entry forms
+- CSV upload forms
+
+### 4. Interactive Elements
+- Modal dialogs for quick actions
+- Dropdown menus
+- Search/filter controls
+- Pagination controls
+
+### 5. Visual Elements
+- Elo rating indicators (with trends)
+- Win/loss badges
+- Partnership confidence indicators
+- Tournament bracket visualization
+
+## Implementation Plan
+
+### Phase 0: Authentication (Week 0)
+- [ ] Create login page
+- [ ] Create registration page
+- [ ] Implement session management
+- [ ] Add navigation for logged-in users
+- [ ] Protect admin routes
+
+### Phase 1: Navigation & Layout (Week 1)
+- [ ] Add navigation bar to all templates
+- [ ] Implement role-based navigation links
+- [ ] Create consistent layout structure
+
+### Phase 2: Player Profile Enhancements (Week 1-2)
+- [ ] Improve profile header with stats grid
+- [ ] Enhance partnership table with confidence indicators
+- [ ] Add recent games timeline
+
+### Phase 3: Tournament Admin View (Week 2-3)
+- [ ] Build tournament dashboard
+- [ ] Implement management tabs
+- [ ] Add match result entry forms
+
+### Phase 4: Club Admin View (Week 3-4)
+- [ ] Create superuser dashboard
+- [ ] Build player directory with search
+- [ ] Add club settings page
+
+### Phase 5: Player Schedule View (Week 4)
+- [ ] Build upcoming matches view
+- [ ] Implement calendar integration
+- [ ] Add bracket visualization
+
+### Phase 6: Polish & Testing (Week 5)
+- [ ] Mobile responsiveness
+- [ ] Accessibility improvements
+- [ ] Cross-browser testing
+- [ ] User feedback incorporation
+
+## Technical Considerations
+
+### Hanami View Structure
+```
+app/
+  actions/
+    players/
+      profile.rb
+      schedule.rb
+    admin/
+      tournaments/
+        index.rb
+        show.rb
+      club/
+        dashboard.rb
+  templates/
+    layouts/
+      app.html.erb
+      admin.html.erb
+    players/
+      profile.html.erb
+      schedule.html.erb
+    admin/
+      tournaments/
+        index.html.erb
+        show.html.erb
+      club/
+        dashboard.html.erb
+```
+
+### CSS Architecture
+- Use Tailwind CSS or custom CSS
+- Consistent color scheme (green for wins, red for losses)
+- Responsive breakpoints for mobile
+- Accessibility: color contrast, focus states
+
+### JavaScript Interactions
+- Calendar navigation
+- Modal dialogs
+- Form validation
+- Real-time updates (optional)
+
+## Success Metrics
+- User satisfaction with navigation
+- Time to complete common tasks
+- Mobile usage statistics
+- Accessibility compliance score