Archery Apprentice Documentation

tournament-ui-implementation-plan

8 min read

Tournament UI Implementation Plan

Overview

This document outlines the complete UI implementation plan for tournament features in the Archery Apprentice app. The plan is organized by implementation phases and priority levels based on our established repository layer and database foundation.

Implementation Foundation ✅

Completed Infrastructure

  • Database Layer: Migration 27→28 completed with tournament integration fields in rounds table
  • Repository Layer: Three tournament repository implementations completed
    • FirebaseTournamentRepository - Online tournament operations with Firestore
    • OfflineTournamentRepository - Full offline tournament functionality
    • HybridTournamentRepository - Offline-first with automatic sync
  • Data Models: Complete tournament domain models with security, privacy, and anti-cheating features
  • Authentication Foundation: Firebase Auth integration with account linking ready

Phase 1: Core Tournament Discovery & Creation (Priority: HIGH)

1.1 Tournament Discovery Screen

File: app/src/main/java/com/archeryapprentice/ui/tournament/TournamentDiscoveryScreen.kt

Features:

  • Real-time tournament search and filtering
  • Location-based tournament discovery (within radius)
  • Tournament category filtering (Indoor, Outdoor, Field, 3D)
  • Distance and skill level filters
  • Tournament status indicators (Open, Full, In Progress, Completed)

UI Components:

@Composable
fun TournamentDiscoveryScreen(
    navController: NavHostController,
    tournamentRepository: TournamentRepository,
    viewModel: TournamentDiscoveryViewModel
)
 
// Key composables:
- TournamentSearchBar()
- TournamentFilterChips()
- TournamentListItem()
- LocationPermissionHandler()
- EmptyDiscoveryState()

Integration Points:

  • Location services for nearby tournaments
  • Real-time tournament availability updates
  • Navigation to tournament details and registration

1.2 Tournament Creation Screen

File: app/src/main/java/com/archeryapprentice/ui/tournament/TournamentCreationScreen.kt

Features:

  • Multi-step tournament creation wizard
  • Basic info: name, description, location, dates
  • Format configuration: category, division, scoring system
  • Participant settings: capacity, skill requirements, registration deadline
  • Privacy controls: public/private, invite-only options
  • Anti-cheating settings: witness requirements, verification rules

UI Components:

@Composable
fun TournamentCreationScreen(
    navController: NavHostController,
    tournamentRepository: TournamentRepository,
    viewModel: TournamentCreationViewModel
)
 
// Key composables:
- CreationWizardStepper()
- BasicInfoForm()
- FormatConfigurationForm()
- ParticipantSettingsForm()
- PrivacyControlsForm()
- AntiCheatSettingsForm()
- TournamentPreview()

Validation:

  • Form validation with real-time feedback
  • Location validation and geocoding
  • Date/time conflict detection
  • Capacity and format validation

1.3 Tournament Details Screen

File: app/src/main/java/com/archeryapprentice/ui/tournament/TournamentDetailsScreen.kt

Features:

  • Complete tournament information display
  • Participant list and registration status
  • Round schedule and format details
  • Leaderboard preview (if tournament started)
  • Registration/withdrawal actions
  • Tournament sharing capabilities

UI Components:

@Composable
fun TournamentDetailsScreen(
    navController: NavHostController,
    tournamentId: String,
    tournamentRepository: TournamentRepository,
    viewModel: TournamentDetailsViewModel
)
 
// Key composables:
- TournamentHeader()
- ParticipantList()
- RoundSchedule()
- RegistrationActions()
- LeaderboardPreview()
- ShareTournamentButton()

Phase 2: Tournament Registration & Management (Priority: HIGH)

2.1 Tournament Registration Flow

File: app/src/main/java/com/archeryapprentice/ui/tournament/TournamentRegistrationScreen.kt

Features:

  • Division and category selection
  • Equipment verification and declaration
  • Witness designation (for verification requirements)
  • Terms and conditions acceptance
  • Registration confirmation

UI Components:

@Composable
fun TournamentRegistrationScreen(
    navController: NavHostController,
    tournamentId: String,
    viewModel: TournamentRegistrationViewModel
)
 
// Key composables:
- DivisionSelectionCard()
- EquipmentDeclarationForm()
- WitnessSelectionFlow()
- TermsAcceptanceCard()
- RegistrationSummary()

2.2 My Tournaments Screen

File: app/src/main/java/com/archeryapprentice/ui/tournament/MyTournamentsScreen.kt

Features:

  • Organized tournament views: Registered, Hosting, Completed
  • Tournament status tracking and notifications
  • Quick actions: view details, withdraw, manage
  • Tournament history and statistics

UI Components:

@Composable
fun MyTournamentsScreen(
    navController: NavHostController,
    tournamentRepository: TournamentRepository,
    viewModel: MyTournamentsViewModel
)
 
// Key composables:
- TournamentTabs()
- RegisteredTournamentCard()
- HostingTournamentCard()
- CompletedTournamentCard()
- QuickActionButtons()

2.3 Tournament Management Screen (Host View)

File: app/src/main/java/com/archeryapprentice/ui/tournament/TournamentManagementScreen.kt

Features:

  • Participant management: approve/reject registrations
  • Tournament settings modification
  • Round schedule management
  • Communication tools: announcements, messages
  • Tournament control: start, pause, end

UI Components (Host Only):

@Composable
fun TournamentManagementScreen(
    navController: NavHostController,
    tournamentId: String,
    viewModel: TournamentManagementViewModel
)
 
// Key composables:
- ParticipantManagementPanel()
- TournamentSettingsPanel()
- RoundScheduleManager()
- AnnouncementComposer()
- TournamentControlPanel()

Phase 3: Tournament Scoring Integration (Priority: HIGH)

3.1 Tournament Round Selection

Integration: Extend existing RoundScoringScreen.kt

Features:

  • Tournament round selection during round creation
  • Automatic tournament format application
  • Participant verification for tournament rounds
  • Round synchronization indicators

UI Changes:

// Add to existing RoundCreationScreen:
- TournamentRoundSelector()
- TournamentFormatApplier()
- ParticipantVerificationStep()
- SyncStatusIndicator()

3.2 Tournament Scoring Enhancements

Integration: Extend existing ActiveScoringScreen.kt

Features:

  • Tournament mode indicator and constraints
  • Real-time leaderboard position tracking
  • Witness verification prompts (when required)
  • Tournament sync status and conflict resolution

UI Enhancements:

// Add to existing ActiveScoringScreen:
- TournamentModeHeader()
- LeaderboardPositionIndicator()
- WitnessVerificationDialog()
- SyncConflictResolver()

3.3 Tournament Round Details

Integration: Extend existing RoundDetailsScreen.kt

Features:

  • Tournament context display
  • Leaderboard position and ranking
  • Tournament-specific statistics
  • Score verification status
  • Sync history and status

UI Additions:

// Add to existing RoundDetailsScreen:
- TournamentContextCard()
- LeaderboardPositionCard()
- TournamentStatsCard()
- VerificationStatusCard()
- SyncHistoryCard()

Phase 4: Leaderboards & Results (Priority: MEDIUM)

4.1 Tournament Leaderboard Screen

File: app/src/main/java/com/archeryapprentice/ui/tournament/TournamentLeaderboardScreen.kt

Features:

  • Real-time tournament standings
  • Division and category filtering
  • Round-by-round score progression
  • Participant performance analytics
  • Export and sharing capabilities

UI Components:

@Composable
fun TournamentLeaderboardScreen(
    navController: NavHostController,
    tournamentId: String,
    viewModel: TournamentLeaderboardViewModel
)
 
// Key composables:
- LeaderboardTabs()
- ParticipantRankingCard()
- ScoreProgressionChart()
- FilterControls()
- ExportActions()

4.2 Tournament Results Screen

File: app/src/main/java/com/archeryapprentice/ui/tournament/TournamentResultsScreen.kt

Features:

  • Final tournament results and awards
  • Performance analytics and insights
  • Comparison with historical performance
  • Certificate and achievement generation
  • Social sharing capabilities

UI Components:

@Composable
fun TournamentResultsScreen(
    navController: NavHostController,
    tournamentId: String,
    viewModel: TournamentResultsViewModel
)
 
// Key composables:
- FinalResultsCard()
- AwardsSection()
- PerformanceAnalytics()
- HistoricalComparison()
- CertificateGenerator()
- SocialSharingActions()

Phase 5: Advanced Features (Priority: LOW)

5.1 Tournament Analytics Dashboard

File: app/src/main/java/com/archeryapprentice/ui/tournament/TournamentAnalyticsScreen.kt

Features:

  • Tournament hosting analytics (for organizers)
  • Participation history and trends
  • Performance metrics across tournaments
  • Comparative analysis tools

5.2 Tournament Social Features

File: app/src/main/java/com/archeryapprentice/ui/tournament/TournamentSocialScreen.kt

Features:

  • Tournament chat and communication
  • Photo sharing and gallery
  • Participant profiles and connections
  • Tournament reviews and ratings

5.3 Tournament Notifications

Integration: Extend existing notification system

Features:

  • Tournament registration confirmations
  • Round start notifications
  • Leaderboard position updates
  • Tournament announcements
  • Score verification requests

ViewModel Architecture

Core ViewModels to Implement

// Discovery and browsing
class TournamentDiscoveryViewModel(
    private val tournamentRepository: TournamentRepository,
    private val locationService: LocationService
)
 
// Tournament lifecycle management
class TournamentCreationViewModel(
    private val tournamentRepository: TournamentRepository,
    private val authRepository: AuthenticationRepository
)
 
class TournamentDetailsViewModel(
    private val tournamentRepository: TournamentRepository
)
 
class TournamentRegistrationViewModel(
    private val tournamentRepository: TournamentRepository,
    private val authRepository: AuthenticationRepository
)
 
// Tournament participation
class MyTournamentsViewModel(
    private val tournamentRepository: TournamentRepository,
    private val authRepository: AuthenticationRepository
)
 
// Tournament scoring integration
class TournamentScoringViewModel(
    private val tournamentRepository: TournamentRepository,
    private val roundRepository: RoundRepository
)
 
// Results and analytics
class TournamentLeaderboardViewModel(
    private val tournamentRepository: TournamentRepository
)
 
class TournamentResultsViewModel(
    private val tournamentRepository: TournamentRepository,
    private val analyticsService: TournamentAnalyticsService
)
 
// Management (host features)
class TournamentManagementViewModel(
    private val tournamentRepository: TournamentRepository,
    private val authRepository: AuthenticationRepository
)

Tournament Navigation Graph

File: app/src/main/java/com/archeryapprentice/ui/tournament/navigation/TournamentNavGraph.kt

@Composable
fun TournamentNavGraph(
    navController: NavHostController,
    repositoryFactory: RepositoryFactory
) {
    navigation(
        startDestination = "tournament_discovery",
        route = "tournament"
    ) {
        composable("tournament_discovery") { /* TournamentDiscoveryScreen */ }
        composable("tournament_creation") { /* TournamentCreationScreen */ }
        composable("tournament_details/{tournamentId}") { /* TournamentDetailsScreen */ }
        composable("tournament_registration/{tournamentId}") { /* TournamentRegistrationScreen */ }
        composable("my_tournaments") { /* MyTournamentsScreen */ }
        composable("tournament_management/{tournamentId}") { /* TournamentManagementScreen */ }
        composable("tournament_leaderboard/{tournamentId}") { /* TournamentLeaderboardScreen */ }
        composable("tournament_results/{tournamentId}") { /* TournamentResultsScreen */ }
    }
}

Integration: Add tournament entry points to existing navigation

// Add to MainActivity or main navigation:
- "Tournaments" tab or menu item
- Tournament creation FAB or action
- Tournament notifications navigation

Repository Integration Strategy

Repository Selection by Build Variant

// Use appropriate repository based on feature flags and build configuration
val tournamentRepository = when {
    BuildConfig.DEBUG -> hybridTournamentRepository // Full feature testing
    FeatureFlags.OFFLINE_TOURNAMENTS_ONLY -> offlineTournamentRepository
    FeatureFlags.ONLINE_TOURNAMENTS_ENABLED -> hybridTournamentRepository
    else -> offlineTournamentRepository // Safe fallback
}

Error Handling and Offline Support

// Consistent error handling across all tournament screens
sealed class TournamentUiState<T> {
    object Loading : TournamentUiState<Nothing>()
    data class Success<T>(val data: T) : TournamentUiState<T>()
    data class Error(val message: String, val canRetry: Boolean = true) : TournamentUiState<Nothing>()
    data class Offline(val cachedData: T? = null) : TournamentUiState<T>()
}

Testing Strategy

UI Testing Plan

// Tournament UI tests to implement
class TournamentDiscoveryScreenTest : BaseComposeTest()
class TournamentCreationScreenTest : BaseComposeTest()
class TournamentDetailsScreenTest : BaseComposeTest()
class TournamentRegistrationScreenTest : BaseComposeTest()
class TournamentScoringIntegrationTest : BaseComposeTest()
 
// ViewModel tests
class TournamentDiscoveryViewModelTest : BaseViewModelTest()
class TournamentCreationViewModelTest : BaseViewModelTest()
class TournamentLeaderboardViewModelTest : BaseViewModelTest()

Repository Integration Testing

// Test tournament repository integrations
class TournamentRepositoryIntegrationTest
class TournamentScoringIntegrationTest
class TournamentOfflineSyncTest

Implementation Timeline

Week 1-2: Foundation & Discovery

  • TournamentDiscoveryScreen implementation
  • TournamentDetailsScreen implementation
  • Basic navigation setup

Week 3-4: Creation & Registration

  • TournamentCreationScreen implementation
  • TournamentRegistrationScreen implementation
  • MyTournamentsScreen implementation

Week 5-6: Scoring Integration

  • Tournament mode integration with existing scoring screens
  • Tournament round creation and management
  • Sync status and conflict resolution UI

Week 7-8: Leaderboards & Results

  • TournamentLeaderboardScreen implementation
  • TournamentResultsScreen implementation
  • Analytics and reporting features

Week 9-10: Advanced Features & Polish

  • Tournament management features (host view)
  • Social features and communications
  • Performance optimization and testing

Success Criteria

Phase 1 Success Metrics

  • Users can discover and view tournament details
  • Tournament creation flow completes successfully
  • Registration process works end-to-end
  • Tournament data syncs correctly between online/offline modes

Phase 2 Success Metrics

  • Tournament rounds integrate seamlessly with existing scoring
  • Real-time leaderboards update correctly
  • Offline tournament functionality works without network
  • Score verification and anti-cheating measures function properly

Phase 3 Success Metrics

  • Complete tournament lifecycle supported (creation → participation → results)
  • Tournament host management tools functional
  • Tournament analytics and reporting available
  • Social features and community engagement working

Risk Mitigation

Technical Risks

  1. Network Connectivity: Offline-first architecture with HybridTournamentRepository
  2. Real-time Updates: Firestore real-time listeners with fallback polling
  3. Data Conflicts: Conflict resolution UI and manual merge capabilities
  4. Performance: Lazy loading and pagination for large tournament lists

User Experience Risks

  1. Complex Workflows: Progressive disclosure and wizard-based flows
  2. Tournament Discovery: Multiple filter and search options
  3. Offline Limitations: Clear offline mode indicators and capabilities
  4. Error Recovery: Comprehensive error handling with retry mechanisms

This plan provides a comprehensive roadmap for implementing tournament features while leveraging our existing repository infrastructure and maintaining consistency with the current app architecture.

Graph View