Data Model

Core Tables

• User (role, wallet, referral code/alias)
• Business (owner and members)
• BusinessBalance (funded, reserved, paid, available)
• BusinessApiKey (environment, hash, allowed origins, lifecycle)
• Referral (referrer -> referred user mapping)
• Reward (amount, status, claim metadata)
• Event (business event definitions)
• EventTrigger (individual ingestion events)

Key Constraints

• One referral per referred user (Referral.referredUserId unique)
• API key idempotency uniqueness (EventTrigger.apiKeyId + idempotencyKey)
• Unique event per business name (Event.businessId + name)
• Reward idempotency key uniqueness (Reward.idempotencyKey)

Reward State Transitions

stateDiagram-v2
  [*] --> PENDING
  PENDING --> CLAIMABLE
  CLAIMABLE --> PROCESSING
  PROCESSING --> CLAIMED
  CLAIMABLE --> EXPIRED
  PROCESSING --> CLAIMABLE: payout failure rollback