Athlete Registration Form & Waiver System

Overview

The BPVA Calendar app now includes a comprehensive document management system for athletes to submit required registration forms and liability waivers. This system provides a complete workflow for document upload, review, approval/rejection, and status tracking.

Key Features

For Athletes

For Admins

For Parents

Document Types

Athletes must submit two required documents:

1. Registration Form

2. Liability Waiver

Accepted File Formats:

File Size Limit: 10 MB per document

Document Status

Each document goes through a review process:

Not Submitted 🔴

Pending Review 🟡

Approved 🟢

Rejected 🔴

Admin Features

Document Review Dashboard

Access via: Admin Dashboard (hamburger menu) → User Management → Document Review

Two Tabs:

Review Actions:

Firestore Collections

athlete_documents

/athlete_documents/{documentId}
  - documentId: string
  - userId: string (athlete's Firebase UID)
  - athleteEmail: string
  - athleteName: string
  - documentType: 'registrationForm' | 'waiver'
  - status: 'pending' | 'approved' | 'rejected' | 'notSubmitted'
  - fileUrl: string (Firebase Storage download URL)
  - fileName: string
  - fileType: string (MIME type)
  - fileSizeBytes: number
  - submittedAt: timestamp
  - reviewedAt: timestamp
  - reviewedByUserId: string
  - reviewedByName: string
  - reviewNotes: string
  - createdAt: timestamp
  - updatedAt: timestamp

Firestore Security Rules

Added to firestore.rules:

match /athlete_documents/{documentId} {
  // Athletes can read/write their own documents
  allow read: if request.auth.uid == resource.data.userId;
  allow create: if request.auth.uid == request.resource.data.userId;
  allow update: if request.auth.uid == resource.data.userId &&
                   (resource.data.status == 'pending' || 
                    resource.data.status == 'rejected');
  allow delete: if request.auth.uid == resource.data.userId;
  
  // Parents can read linked athletes' documents
  allow read: if request.auth.uid in 
                 firestore.get(/databases/$(database)/documents/user_memberships/$(request.auth.uid))
                 .data.linkedAthleteIds;
  
  // Admins can read all and update status (approve/reject)
  allow read, update: if isAdminUser();
}

Firebase Storage

Storage Path: athlete_documents/{userId}/{documentType}_{timestamp}.{ext}

Storage Security Rules (storage.rules):

match /athlete_documents/{userId}/{fileName} {
  // Athletes can upload their own documents (max 10MB, PDF/images only)
  allow write: if request.auth.uid == userId &&
                  request.resource.size < 10 * 1024 * 1024 &&
                  (request.resource.contentType.matches('application/pdf') ||
                   request.resource.contentType.matches('image/.*'));
  
  // Athletes, parents, and admins can read
  allow read: if request.auth.uid == userId ||
                 userId in firestore.get(/databases/(default)/documents/user_memberships/$(request.auth.uid))
                 .data.linkedAthleteIds ||
                 isAdminUser();
}

User Workflow

Athlete Journey

  1. Initial State
    • Athlete signs up and creates account
    • Profile shows “Required Documents” card with warnings
    • Both documents show “Not Submitted” status
  2. Upload Registration Form
    • Tap “Manage Documents” button
    • Select “Upload” for Registration Form
    • Choose PDF or image file from device
    • File uploads to Firebase Storage
    • Status changes to “Pending Review”
  3. Upload Waiver
    • Same process for waiver document
    • Both documents now pending
  4. Admin Review
    • Admin reviews in admin dashboard
    • If Approved: Status changes to “Approved”, green checkmark shows
    • If Rejected: Status changes to “Rejected”, admin provides reason
  5. Resubmission (if rejected)
    • Athlete sees rejection reason in red alert box
    • “Resubmit” button appears
    • Upload corrected document
    • Status changes back to “Pending Review”
  6. Completion
    • Both documents approved
    • Profile shows green “All required documents completed!” banner
    • Athlete is fully registered

Admin Workflow

  1. Access Review Screen
    • Open Admin Dashboard (hamburger menu)
    • Tap User Management expansion tile
    • Tap “Document Review” option
    • See pending documents count in tab badge
  2. Review Pending Document
    • Tap on document card to expand details
    • View athlete name, email, document type
    • Tap “View” to open document in browser/viewer
  3. Approve Document
    • Tap “Approve” button
    • Optionally add approval notes
    • Document marked as approved
    • Removed from pending list
  4. Reject Document
    • Tap “Reject” button
    • Required: Enter rejection reason
    • Document status changes to rejected
    • Athlete receives feedback
  5. Monitor Statistics
    • View overall stats: total, pending, approved, rejected
    • Track document types: registration forms vs waivers
    • Use “All Documents” tab to see history

File Type Support

Supported Formats:

File Size Limit: 10MB per document

Storage Location: Firebase Storage bucket athlete_documents/

Integration with Existing Features

User Management

Gym Check-In

Membership Management

Future Enhancements

Planned Features

  1. Email Notifications
    • Notify admins when new documents submitted
    • Notify athletes when documents reviewed
    • Reminder emails for incomplete documents
  2. In-App PDF Viewer
    • View PDFs without leaving app
    • Zoom and annotation support
    • Signature capture for digital signing
  3. Document Templates
    • Downloadable blank forms
    • Pre-fill with athlete information
    • Digital signature fields
  4. Expiration Tracking
    • Set expiration dates for waivers (e.g., annual renewal)
    • Automatic reminders before expiration
    • Bulk renewal notifications
  5. Parent Signatures
    • For minor athletes (under 18)
    • Require parent to sign waiver
    • Parent approval workflow
  6. Batch Operations
    • Approve/reject multiple documents at once
    • Export document list to CSV
    • Print document checklists
  7. Mobile Scanning
    • Use camera to scan physical forms
    • Auto-crop and enhance
    • Convert to PDF automatically

Testing

Unit Tests (to be created)

// Test document service operations
test/services/document_service_test.dart

// Test document model serialization
test/models/athlete_document_test.dart

Integration Tests (to be created)

// Test upload workflow
test/integration/document_upload_test.dart

// Test admin review workflow
test/integration/document_review_test.dart

Manual Testing Checklist

Athlete Tests:

Admin Tests:

Parent Tests:

Deployment Checklist

  1. Install Dependencies 
    flutter pub get
  2. Deploy Firestore Rules 
    firebase deploy --only firestore:rules
  3. Deploy Storage Rules 
    firebase deploy --only storage
  4. Build and Test 
    # Test on dev environment
./run.sh dev
   
# Build for production
./build.sh prod
  5. Verify Firebase Console
    • Check Firestore collection created on first upload
    • Verify Storage bucket has correct permissions
    • Test file upload/download URLs work

Troubleshooting

Common Issues

“Error uploading document”

“Cannot view document”

“Permission denied”

Documents not showing in admin panel

Code Locations

Models: lib/models/athlete_document.dart

Services: lib/services/document_service.dart

Athlete Screens:

Admin Screens:

Firebase Configuration:

Dependencies Added

pubspec.yaml:

dependencies:
  firebase_storage: ^12.4.0  # File upload/download
  file_picker: ^10.3.7       # Already present - file selection
  url_launcher: ^6.2.1       # Already present - open documents

Support

For issues or questions about the document system:

  1. Check this README first
  2. Review Firebase Console for errors
  3. Check app logs for detailed error messages
  4. Contact development team with specific error details