Skip to content

Challenges Platform Overview

Data Model

  • Challenge: template describing a global, club, or personalized goal. Supports XP rewards, optional badges, difficulty levels, duration, and JSON rules for complex triggers.
  • ChallengeParticipation: tracks who joined, current status, optional progress/result payloads, and sharing flags (shareWithinClub, shareGlobally).
  • ChallengeScope enum differentiates global, club, and personal templates. Club-scoped challenges reference a clubId, personal templates can be bound to a personalizedForUserId.
  • ChallengeVisibility default controls suggested sharing; participation toggles start private.
  • ChallengeParticipationStatus records lifecycle (active, completed, failed, cancelled).

API Surfaces (planned)

  • GET /api/challenges – returns lists for global, club, and personalised scopes based on authenticated user and clubs. Supports filtering by status/difficulty.
  • GET /api/challenges/:id/leaderboard – returns global or club leaderboard rows (XP/points) respecting visibility preferences.
  • POST /api/challenges/:id/join – creates a ChallengeParticipation using the user’s sharing preferences.
  • PATCH /api/challenges/participations/:id/visibility – toggles shareWithinClub / shareGlobally flags.
  • POST /api/challenges – admins and club leaders may create predefined templates; supports optional clubId, level bounds, price, and XP reward.
  • POST /api/challenges/personalize – service endpoint that generates adaptive goals based on historical averages + difficulty multiplier.

Frontend Experience

  • Three tabs (Global, Verein, Personalisiert) with search and filter controls.
  • Challenge cards show scope badges, target metrics, XP reward, and call-to-action.
  • Personal tab exposes privacy toggles (default off) mapped to shareWithinClub / shareGlobally.
  • Adaptive challenges highlight recommended goals (e.g., +5% above personal average) and allow quick regeneration.
  • Team/community cards visualise aggregate progress (ring count, contribution breakdown), enabling cooperative goals.
  • Leaderboard panel inside each card can toggle between Global and Club rankings.
  • Profile “Achievements & Badges” panel summarises XP tier, earned badges, and latest completions.
  • TargetShot Connect UI now has a “Reset & Re-Snapshot” action that deletes the Debezium connector, recreates it, and triggers a full snapshot so non-technical staff can repopulate Kafka/Postgres after resets.

Wireframe (Desktop Challenge Card)

┌─────────────────────────────────────────────┐
│ [Global] [72h] [Level 2]                    │
│ Precision Sprint                            │
│ Average ≥ 9.4 across 30 shots               │
│                                             │
│ 🎯 Ø ≥9.4   ⭐ 600 XP   🏅 Silver Precision  │
│                                             │
│ [View details] [Show leaderboard]   [Join]  │
│ Progress: private (toggle to share)         │
│                                             │
│ ┌ Leaderboard (Global / Club tabs) ┐        │
│ │ #1 Lena    650 pts  Completed     │       │
│ │ #2 Markus  620 pts  Completed     │       │
│ └──────────────────────────────────┘        │
└─────────────────────────────────────────────┘

Wireframe (Profile Achievements block)

┌────────────── Achievements ────────────────┐
│ Tier: Silver  •  2,480 XP  (340 XP → Gold) │
│                                             │
│ Badges: [Silver Precision] [Bronze Team]…   │
│                                             │
│ Recent completions                          │
│  • Precision Sprint — 07 Oct — 600 XP       │
│  • Vereins-Push 500 — shared with club      │
└─────────────────────────────────────────────┘

Badges, XP & Tiers

  • XP Economy
  • Every challenge pays out XP (rewardXp) on completion. XP feeds into a tier ladder that unlocks cosmetic rewards and highlights on the profile page.
  • Suggested tier thresholds (cumulative XP):
    • Iron: 0 – 499 XP
    • Bronze: 500 – 1,499 XP
    • Silver: 1,500 – 3,499 XP
    • Gold: 3,500 – 6,999 XP
    • Platinum: 7,000 – 11,999 XP
    • Diamond: 12,000+ XP
  • XP ladders should support seasonal resets (optional) and lifetime totals.
  • Badges
  • Challenges can reference a rewardBadge string in rulesJson. When the badge is defined, completing the challenge grants both XP and the badge.
  • Badge metadata (icon, colour, description) is managed in a small registry keyed by rewardBadge.
  • Badge quality mirrors tier ladders (Iron/Bronze/Silver/Gold/Platinum/Diamond) so league-style goals can grant tiered emblems.
  • Personal Space Integration
  • Add an “Achievements & Badges” block to the profile page summarising:
    • Current XP, tier, and progress to the next tier.
    • Earned badges grouped by quality and sorted chronologically.
    • Recently completed challenges with quick access to their leaderboards.
  • Provide toggles to hide/show badges that stem from private challenges (respect shareWithinClub / shareGlobally).
  • Include links back to the Challenges page to encourage starting new goals.

Sample Challenge Catalogue

Example presets for seeding the catalogue (5 per scope):

Global Challenges

  1. Precision Sprint – Average ≥ 9.4 across 30 shots within 72 hours (reward: 600 XP, Silver badge).
  2. Weekend Highscore Blitz – Set a personal best total between Friday 18:00 and Sunday 23:59 (reward: 550 XP, Silver badge).
  3. Ten-Point Frenzy – Log 25 inner tens in a single session (reward: 700 XP, Gold badge).
  4. Consistency Champion – Complete 4 sessions in a week with ≥ 90% hit ratio (reward: 800 XP, Platinum badge).
  5. Global Duo Duel – Win three duels against random opponents (best-of-three) in 10 days (reward: 900 XP, Gold badge).

Club Challenges (Vereins-intern)

  1. Vereins-Push 500 – Collectively reach 500 recorded rings in 5 days (reward: 400 XP + Bronze badge for participants).
  2. Team Precision Ladder – Average ≥ 9.3 over a combined 200 shots across club members (reward: 650 XP, Silver badge).
  3. Trainer’s Choice – Coach picks a target (e.g. 95 total) to be achieved by at least 3 shooters (reward: 550 XP, Bronze badge).
  4. Club Duel Cup – Knockout bracket; winner earns 1,000 XP and a Gold badge, finalists receive 600 XP.
  5. Morning Warriors – Members log training before 10:00 on three consecutive days (reward: 500 XP, Bronze badge).

Personalised Challenges

  1. Adaptive Average +3% – Personal best average +3% over 40 shots (reward: 450 XP, personalised Iron badge).
  2. Steady Hand – Beat personal deviation from centre by 10% in next two sessions (reward: 500 XP, Iron badge).
  3. Hit Streak – Achieve 15 consecutive 10s relative to user baseline (reward: 600 XP, Silver badge).
  4. Calm Weekend – Complete two sessions with <30s average interval between shots, improving pacing (reward: 550 XP, Bronze badge).
  5. Adaptive Duel Practice – Compete against AI/preset target based on historical average; beat target three times (reward: 650 XP, Silver badge).

Seeding Sample Challenges

  • Script: npm run seed:challenges
  • Environment variables:
  • SEED_CLUB_ID – optional, seeds club templates for the given Club.id.
  • SEED_PERSONAL_USER_ID – optional, seeds personalised templates for the given User.id.
  • Execution example:
SEED_CLUB_ID=123e4567 SEED_PERSONAL_USER_ID=auth0|abc npm run seed:challenges
  • The script uses upsert so re-running updates templates non-destructively.

Open Questions

  • Badge/catalog design for monetized challenges (priceCents).
  • How to evaluate consistency metrics (daily tracker) and duel match-making.
  • Cron/scheduler integration to auto-complete/end challenges once duration passes.
  • Notification hooks for milestone updates and challenge completion.