Gamification Platform – Phase 1 HLD

1. Summary

The gamification platform is an event-driven runtime for reward-bearing customer journeys that must not sit on the payments critical path. It consumes events, evaluates eligibility, progresses users through linear milestone journeys, and orchestrates NeuCoin/voucher rewards asynchronously. PostgreSQL is the authoritative store; Redis holds projection caches; Confluent Cloud Kafka is the streaming platform.

Phase 1 delivers a JSON-configured, count-based milestone game using a single archetype NUMERIC_COUNTER. UPI and FS events both drive the same numeric counter via config-defined triggers. The design keeps the hot path short and deterministic, while the config and event models are extensible to future gamification archetypes (amount, category, checklist, streak, daily grid).

---

2. Scope and Non-Goals

2.1 In Scope (Phase 1)

• Progress drivers

  • payment_success events with transaction_type = "UPI" (UPI to anybody on Tata Neu).
  • fs_action_complete events for selected FS actions (e.g., credit card apply, loan enquiry, insurance purchase, bill payments - these would be sub categories).

• Game archetype and progression

  • NUMERIC_COUNTER – numeric progress state (count) with linear steps 1 -> 2 -> … -> N.
  • Milestone steps typed as REWARD, EMPTY, or FORTUNE_COOKIE (Fortune Cookie is data-model-ready in P1; UI can ship later).
  • Rewards: NeuCoins and vouchers, with visibility: visible|hidden and display_type: flat|upto.

• Config/runtime

  • Versioned JSON configs for each game; no admin/config UI in Phase 1.
  • Event-time config version pinning per user/game.
  • Triggers configured over canonical event attributes (UPI + FS), not hard-coded in code.

• Cohorts & eligibility

  • Cohorts defined and owned by Viduur/LaunchDarkly; config only references cohort_id.
  • Event-time eligibility is always evaluated via LaunchDarkly before progression.

• Rewards

  • Reward entitlements recorded in Postgres.
  • Provider grants via Capillary (NeuCoins) / Offer Engine (vouchers) are asynchronous with idempotent keys.

2.2 Explicit Non-Goals (Phase 1)

• Other categories (commerce orders, app-opens) as progression drivers.
• Additional archetypes (checklist, category grid, streak, calendar grid) – architecturally anticipated but not implemented.
• Admin/config UI – deferred; JSON + validation/activation APIs are the contract.
• FRM logic – product expects FRM might appear as an attribute in future events, but no concrete contract/behaviour exists.
• Reversal ingestion, progress rollback, or provider-side clawback – product has no defined strategy; Phase 1 does not build these paths, but keeps history to make future clawback feasible.

---

3. Architecture Overview

3.1 System Architecture

The system consists of four main layers:

External Systems:

• Payments (UPI) and Financial Services producing events
• Viduur providing cohorts to LaunchDarkly
• LaunchDarkly for eligibility evaluation
• Capillary (NeuCoins) and Offer Engine (vouchers) for reward fulfillment
• MoEngage for push notifications

Event Streaming:

• Confluent Cloud Kafka as the streaming platform

Gamification Runtime:

• Event Consumer – subscribes to Kafka topics
• Eligibility Gate – validates user eligibility via LaunchDarkly
• Normalisation Layer – maps producer payloads to canonical events
• Game Engine – core progression logic
• NumericCounterStrategy – implements count-based progression
• Config Loader & Registry – manages versioned JSON configs
• Reward Orchestrator – async reward disbursement
• Projection & Game API (BFF) – client-facing read APIs
• Scheduled Jobs – notifications and maintenance

Data Layer:

• PostgreSQL – authoritative state store
• Azure Cache for Redis – projection cache

Client:

• App Screens consuming Game APIs

Key decisions:

• Postgres is authoritative; Redis is a non-authoritative projection cache.
• Kafka provides ordered, replayable ingestion.
• A single archetype NUMERIC_COUNTER is supported in P1 with typed triggers; there is no generic rule engine in the hot path.
• Normalisation is a thin internal boundary that isolates the engine from producer schema drift; its deployment shape is under deliberation but remains gamification-owned.

---

4. Config Model (JSON-Driven)

Note: DB schemas are WIP and will be derived from these JSON models; JSON is the primary configuration contract.

4.1 Game Config Schema – Phase 1

Top-level fields:

• schema_version – config schema version.
• game_id – unique game identifier.
• game_archetype – "NUMERIC_COUNTER" in P1.
• cohort_id – Viduur/LaunchDarkly segment key; only cohort field in config.
• game_window – { start, end, type } (monthly/quarterly).
• progress_state_model – numeric state representation.
• milestone_steps[] – ladder with step types and rewards.
• triggers[] – declarative triggers over canonical event attributes.

4.1.1 Example: UPI + FS Milestone Game

{
  "schema_version": "1.0",
  "game_id": "upi_fs_milestone_may_2026",
  "game_archetype": "NUMERIC_COUNTER",

  "cohort_id": "viduur_segment_upi_fs_early_lifecycle",

  "game_window": {
    "start": "2026-05-01T00:00:00Z",
    "end": "2026-05-31T23:59:59Z",
    "type": "monthly"
  },

  // this would vary per game archetype in future
  // mapped to each game strategy (numeric counter for now)
  "progress_state_model": {
    "type": "numeric_counter",
    "unit": "count",
    "display_unit": "transactions",
    "max_value": 12
  },

  "milestone_steps": [
    { "step": 3,  "step_type": "REWARD",
      "reward": {
        "reward_type": "NC",
        "value": 10,
        "visibility": "visible",
        "display_type": "flat"
      }
    },
    { "step": 6,  "step_type": "REWARD",
      "reward": {
        "reward_type": "NC",
        "value": 30,
        "visibility": "hidden",
        "display_type": "upto"
      }
    },
    { "step": 12, "step_type": "REWARD",
      "reward": {
        "reward_type": "NC",
        "value": 100,
        "visibility": "visible",
        "display_type": "flat"
      }
    }
  ],

  "triggers": [
    {
      "trigger_id": "upi_plus_one",
      "event_type": "payment_success",
      "rule": {
        "operator": "and",
        "conditions": [
          { "field": "attributes.payment_status", "op": "eq", "value": "SUCCESS" },
          { "field": "attributes.transaction_type", "op": "eq", "value": "UPI" },
          { "field": "attributes.transaction_amount", "op": "gte", "value": 1200 }
        ]
      },
      "progression_config": {
        "mode": "increment_by_constant",
        "value": 1
      }
    },
    {
      "trigger_id": "fs_plus_three",
      "event_type": "fs_action_complete",
      "rule": {
        "operator": "and",
        "conditions": [
          { "field": "attributes.action_type", "op": "eq", "value": "CREDIT_CARD_APPLY" }
        ]
      },
      "progression_config": {
        // this config will vary for future games to increment by attribute fields such as .attributes.txn_amount
        "mode": "increment_by_constant",
        "value": 3
      }
    }
  ]
}

FS cross-sell is just another trigger (higher value) on FS events, not a separate skip/config block. This scales naturally to more FS actions or other event types.

4.2 Config Validation and Versioning

• Config Loader validates JSON (schema and semantics) and compiles it into an internal representation cached in Redis.
• For each new user/game, the engine pins a game_config_version based on occurred_at (event-time version resolution).
• Amendments (PATCH) can adjust milestones, rewards, or windows for future hits; entitlements already created use the config version active at time of hit.

---

5. Event Model and Normalisation

5.1 Normalisation Layer

The Normalisation Layer:

• Maps producer payloads to a canonical event structure.
• Validates mandatory fields (e.g., stable event_id, user_id, occurred_at, event type, key attributes).
• Remains within the gamification boundary; progression strategies see only canonical events, not producer specifics.
• May be deployed as:
  • a distinct internal service, or
  • code within the Event Consumer.
    Final shape is a deployment decision; the contract is fixed in the HLD.

5.2 Normalised Events (Phase 1)

5.2.1 UPI Payment

{
  "event_id": "evt_pay_001",
  "event_type": "payment_success",
  "event_version": "1.0",
  "occurred_at": "2026-06-10T11:05:00+05:30",
  "producer": "payments",
  "user_id": "U123",
  "correlation": {
    "payment_id": "pay_123",
    "txn_id": "txn_123", // FS correlation?
    "canonical_transaction_id": "txn_123",
    "original_event_id": null // FS correlation?
  },
  "attributes": {
    "transaction_type": "UPI",
    "payment_status": "SUCCESS",
    "transaction_amount": 25000,
    "currency": "INR",
    "merchant_id": "m_001",
    "merchant_category": "UTILITY",
    "action_type": null
  }
}

Future games leverage the same attributes.* space (e.g., merchant_category, billpay_category) in their triggers, giving us config-only extensibility.

---

6. Runtime Flows

6.1 Forward Write Path

Sequence:

1. Producer (PAY/FS) publishes event to Kafka
2. Event Consumer receives event from Kafka
3. Consumer calls LaunchDarkly for event-time eligibility check using cohort_id
4. If ineligible: drop event (no state mutation)
5. If eligible:
   • Consumer invokes Normalisation Layer
   • Normalisation Layer returns canonical event
   • Consumer passes canonical event to Game Engine
6. Game Engine begins PostgreSQL transaction:
   • Load user_game_counter for game_id
   • If no enrollment: rollback and return SKIP_NO_ENROLLMENT
   • If enrolled:
     • Insert into processed_events(event_id,...)
     • If duplicate event_id: rollback (unique violation)
     • If new event:
       • Evaluate triggers[] for this event
       • Apply NumericCounterStrategy (increment by sum of deltas)
       • Evaluate milestone_steps and create reward_entitlement rows
       • Commit transaction
7. Engine invalidates projection cache in Redis for user/game
8. Engine notifies Reward Orchestrator of pending entitlements (async)

Evaluation scope: Phase 1 uses INBOUNDEVENT evaluation only; no logical-transaction correlation is applied. Trigger stacking (multiple triggers on the same event) is supported via mode: ADDITIVE but is not required for UPI+FS Phase 1.

---

7. Data and State Model

7.1 State Ownership

• PostgreSQL owns all mutable and auditable business state.
• Redis owns ephemeral projection cache, config cache, and dedup hints.

7.2 Storage Strategy

• Normalize mutable state in PostgreSQL.
• Use ledger-style tables for contribution and entitlement tracking.
• Archive closed-window operational state on a schedule.
• Cache only fully derived view models and runtime hints in Redis.

7.3 Archival Strategy

• Scheduled Jobs archive closed-window operational rows from hot tables into archive tables using game-window and lifecycle state as the boundary.
• Hot tables remain optimized for active campaigns and recent operational investigation.
• Archive tables remain queryable for audit, support, and financial investigation, but are excluded from latency-sensitive read paths.

7.4 Canonical Event Structure

{
  "event_id": "evt_001",
  "event_type": "payment_success",
  "event_version": "1.0",
  "occurred_at": "2026-06-10T11:05:00+05:30",
  "producer": "payments",
  "user_id": "U123",
  "correlation": {
    "payment_id": "pay_123",
    "txn_id": "txn_123",
    "original_event_id": null
  },
  "attributes": {
    "transaction_type": "UPI",
    "payment_status": "SUCCESS",
    "transaction_amount": 25000,
    "currency": "INR",
    "merchant_id": "m_001",
    "merchant_category": "GROCERY",
    "billpay_category": null,
    "action_type": null,
    "frm_flag": null
  }
}

---

8. Read Path & UX

8.1 BFF Read Path

Homepage widget – GET /api/games/active

• Returns active game summary for the user: current_value, max_value, next visible reward, window remaining.

Game Journey – GET /api/games/{game_id}

• Returns milestone ladder (steps, types, reward metadata), cumulative rewards, current position.

History/support – GET /api/games/{game_id}/history

• Returns event contributions and reward entitlements with status for support and analytics.

BFF pattern:

1. App calls BFF endpoint (GET /api/games/active)
2. BFF checks Redis for projection:dashboard:{user_id}
3. If cache hit: return projection
4. If cache miss:
   • BFF queries PostgreSQL (user_game_counter, reward_entitlement)
   • BFF assembles DTO
   • BFF sets projection in Redis with TTL
   • Return response to App

8.2 Frontend Responsibilities

• Render server-supplied state; do not author progress values.
• Apply bounded optimism only when explicitly allowed (see below).

8.3 Post-Transaction Screen Behaviour (WIP – UX Dependent)

The write path is fully event-driven, so the engine does not expose a synchronous mutation API for post-transaction screens. UX will choose one of two patterns, to be finalised based on approved Figma flows:

1. Optimistic post-transaction UI (preferred where safe)

• For simple games where each qualifying event contributes a fixed, deterministic delta (e.g., +1 for UPI success, +3 for a qualifying FS action), the client can render optimistic progress immediately using:
  • last known server progress from the BFF, and
  • the local transaction result.
• Engine then processes the event, and subsequent screens (homepage, Journey) reflect authoritative state.

2. Authoritative but delayed UI (fallback)

• If UX requires strictly authoritative progress on post-TX, the app:
  • calls BFF after transaction success and accepts that the increment may not yet be visible if the pipeline hasn't processed the event, or
  • shows a "processing your progress" state and re-queries BFF after a short delay.
• This avoids duplicating progression logic outside the engine but introduces a timing gap between transaction completion and visible milestone updates.

this is work in progress and will be finalised once UX figmas are signed off; architecture supports both patterns without additional backend components.

---

9. Extensibility

Although Phase 1 is limited to UPI + FS and a linear milestone game, the architecture generalises cleanly:

New progress drivers – commerce orders, app opens, and other events can be onboarded by:

• adding producer -> Kafka -> Normalisation mappings, and
• defining new triggers over their attributes.*.

New archetypes – checklist, streak, and calendar grid games can be implemented as additional strategies behind the same engine contract, with corresponding config extensions (e.g., per-category targets, streak windows).

New progression modes – amount-based, weighted, uniqueness-based are already part of the NUMERIC_COUNTER design and only require additional progression_config enums and strategy logic, not new infrastructure. In case of newer archetypes such as streaks, calendar based games, etc are introduced, we introduce new Game Strategy plugin to handle such games.

Admin UI – A future admin/config portal can sit on top of the JSON validation and activation APIs without changing the runtime responsibilities.

---

10. Risks and Open Items

1. UPI + FS double-dipping (same logical transaction)

• If an FS purchase is made via Tata Neu BillPay, a single user action could emit both payment_success and fs_action_complete.

2. FRM integration undefined

• FRM handling (e.g., excluding users, pausing counters, holding rewards) is deliberately out of scope for Phase 1 and must be addressed in a future iteration.

3. Clawback/reversal strategy undefined

• Product has no agreed behaviour for reversals, locked vs unlocked rewards, or clawback from providers. Phase 1 does not ingest or process reversals.

4. Normalisation layer deployment shape

• Whether Normalisation is deployed as a standalone internal service or folded into the Consumer remains open; both options must preserve ownership inside gamification and the normalisation event contract.

5. DB schema details are WIP

• Actual table DDL and indexing strategy will be finalised during implementation and performance testing, keeping the conceptual relationships above intact.

---

TLDR