Achievement System

The achievement system is a data-driven engine — admins create achievements and rules via the admin panel with zero code changes. When users perform actions in the app, events are published to NATS JetStream, and a background worker evaluates achievement progress.

Architecture

User Action (login, trade, deposit, etc.)
    │
    ▼
UseCase fires SendEvent() ──► NATS JetStream
                                stream: ACHIEVEMENTS
                                subject: achievements.events.<userID>
                                │
                                ▼
                        Achievement Worker
                        (durable pull consumer)
                                │
                                ▼
                    CheckAchievementActivity()
                        ├── calculateSignalData() ──► DB queries for all metrics
                        ├── loadActiveAchievements() ──► DB: active, non-expired
                        ├── evalProgress() ──► comparator-based evaluation
                        ├── upsertUserAchievement() ──► update progress %
                        ├── grantRewards() ──► apply consumable rewards
                        └── sendNotification() ──► in-app notification

Events

Every significant user action fires an achievement event. The achievement worker recalculates ALL metrics from the database on each event — events are triggers, not data carriers.

All Event Types

Metrics

The achievement engine computes 13 metrics from the database at evaluation time. Adding a new achievement rule using any of these metrics requires NO code changes — just create it in the admin panel.

Rule Comparators

Each achievement rule specifies a comparator that determines how progress is calculated:

Weighted Multi-Rule Achievements

Achievements can have multiple rules with weights that sum to 100:

Achievement: "Trading Master"
├── Rule 1: wins gte 10, weight 50      → 50% of progress
├── Rule 2: total_profit gte 500, weight 30  → 30% of progress
└── Rule 3: trades_closed gte 100, weight 20  → 20% of progress

Total progress = sum(each rule's progress × weight)
Completed when total >= 100

Reward Disbursement

When an achievement is completed for the first time:

1. The rewards edge is loaded (links to Consumable items)
2. Each consumable is applied to the user via ApplyConsumable
3. An in-app notification is sent (ACHIEVEMENT_UNLOCKED)
4. The UserAchievement record is marked is_completed = true with completed_at timestamp

A double-grant guard ensures rewards are only granted once — if CheckAchievementActivity runs again for an already-completed achievement, it skips reward granting and notification.

Worker Deployment

The achievement worker is a separate binary:

go run . achievement

It runs a NATS JetStream durable pull consumer on stream ACHIEVEMENTS with subjects achievements.events.>. Messages are processed by a semaphore-bounded goroutine pool (max 50 concurrent workers).

Scaling: Run multiple instances of the achievement worker — JetStream automatically load-balances messages across consumers with the same durable name.

Creating Achievements (Admin Panel)

Step 1: Create Achievement Rules

In the admin panel, navigate to Achievement Rules and create rules:

Step 2: Create Achievement

Navigate to Achievements and create:

Step 3: Test

1. Log in as a test user
2. Play and win 5 matches
3. Check achievement progress via UserAchievement query
4. On 5th win, the achievement completes automatically

No deployment or code changes needed.

GraphQL API

Query User Achievements

query {
  profile {
    achievements {
      edges {
        node {
          id
          progress
          isCompleted
          completedAt
          achievement {
            name
            key
            avatar
            description
          }
        }
      }
    }
  }
}

Admin: Seed Permissions

mutation {
  seedPermissions
  seedAchievements
}

Seed Achievements (Built-in)

The following achievements are seeded via seedAchievements mutation: