RefKit Docs
System Architecture

Runtime Flow

Exact branching and processing behavior for track and referral ingestion.

/track Controller Decision

trackEvent behavior:

  • if event is not referral: process inline
  • if event is referral without referral context: process inline
  • if event is referral with referrer + referred identity: queue job

Referred identity is detected from metadata keys including both camelCase and lowercase variants.

/sdk/referrals/apply Controller Decision

applyReferral behavior:

  • with referredUserId: process inline
  • with only referredUserEmail: queue job

Worker Dispatch

processJob dispatches by job.name:

  • EVENT_PROCESS -> sdkEventService.trackEventWithApiKey
  • SDK_REFERRAL_APPLY -> sdkReferralService.applyReferralWithApiKey
  • REWARD_PROCESS -> reserved placeholder response

Retry + DLQ

  • Attempts: 5
  • Backoff: exponential, delay 2000ms baseline
  • Exhausted jobs are copied to dead-letter queue with payload + failure stack

System Architecture

Reference architecture for API, worker, Redis queue, and database.

Data Model

Core entities and relationships used in referral and reward processing.

On this page

/track Controller Decision/sdk/referrals/apply Controller DecisionWorker DispatchRetry + DLQ