epic(profile): User Profiles & Personalization

[arunderwood]

Epic Overview

Implement user profile system with hybrid storage (LocalStorage for anonymous users, database sync for logged-in users). Enable personalized dashboard experience based on user preferences.

Architecture Decisions

• Storage Strategy: Hybrid approach
  • Anonymous users: Preferences in browser LocalStorage
  • Logged-in users: Preferences synced to PostgreSQL database
  • "Login to sync across devices" as value-add for authentication
• Profile Fields: Callsign, QTH grid square (Maidenhead), preferred bands, preferred modes
• Personalization: Boost scoring for activities matching user preferences

Use Cases

1. Anonymous user: Sets grid square to FN31, prefers 20m and FT8. Dashboard prioritizes relevant activities.
2. Logged-in user: Same preferences, but synced across devices. Login on mobile, preferences already there.
3. Satellite passes (future): Filter passes visible from user's grid square.
4. Contest filtering: Show only contests with user's preferred modes.

Dependencies

• Requires: epic(admin): Admin Force Refresh with OAuth2 Authentication #203 (Admin Force Refresh) - OAuth2 authentication foundation

Sub-Issues

This epic is broken into 5 sub-issues:

1. feat(profile): Design user profile schema (ADR) #310 - Design user profile schema (ADR)
2. feat(profile): Implement LocalStorage preferences for anonymous users #311 - Implement LocalStorage preferences for anonymous users
3. feat(profile): Implement user profile persistence for logged-in users #312 - Implement user profile persistence for logged-in users
4. feat(profile): Create preferences UI #313 - Create preferences UI
5. feat(profile): Implement preference-based filtering #314 - Implement preference-based filtering

Dependencies Graph

#310 (Profile Schema ADR)
    └── #311 (LocalStorage Preferences)
            └── #312 (DB Profile Persistence)
                    └── #313 (Preferences UI)
                            └── #314 (Preference-Based Filtering)

Key Files

New Files

• docs/adr/004-user-profiles-architecture.md
• src/main/java/io/nextskip/auth/api/ProfileEndpoint.java
• src/main/java/io/nextskip/auth/persistence/entity/UserProfileEntity.java
• src/main/java/io/nextskip/auth/persistence/repository/UserProfileRepository.java
• src/main/resources/db/changelog/xxx-add-user-profiles-table.xml
• src/main/frontend/hooks/usePreferences.ts
• src/main/frontend/components/PreferencesModal.tsx

Modified Files

• src/main/frontend/components/activity/usePriorityCalculation.ts - preference-based scoring
• src/main/frontend/views/DashboardView.tsx - settings button in header

Verification

1. Set preferences as anonymous user
2. Login via GitHub
3. Verify preferences synced to database
4. Logout and login again - preferences restored
5. Change a preference on another device (or incognito) - verify sync