System Architecture

Components

• API (apps/api): Express routes, validation, auth, queue producers, business services.
• Worker (apps/worker): BullMQ consumer for ingestion jobs and DLQ fallback.
• Redis: queue storage for refkit-ingestion and refkit-dead-letter.
• PostgreSQL + Prisma: system of record for users, referrals, events, rewards, balances.
• Blockchain adapter: payout and funding verification via ethers in refkitDistributor.

Ingestion Topology

flowchart LR
  Client[Partner Site or SDK] --> API[API /track or /sdk/referrals/apply]
  API -->|sync branch| Service[Business Logic Services]
  API -->|async branch| Q[(Redis refkit-ingestion)]
  Q --> Worker[Worker processJob]
  Worker --> Service
  Worker -->|terminal failure| DLQ[(Redis refkit-dead-letter)]
  Service --> DB[(PostgreSQL)]
  Service --> Chain[EVM Distributor Contract]

Design Intent

• Keep controllers thin and push business behavior into service modules.
• Allow sync response paths for low-latency and idempotent-safe operations.
• Use async queue path for potentially expensive referral resolution and retries.