Market Module

The Market Module is responsible for managing affiliate marketing systems within the Helium platform. It provides comprehensive affiliate functionality including invite codes, referral tracking, reward calculation, and revenue distribution.

Overview

The market module implements a complete affiliate marketing system that allows users to invite new customers and earn commissions from their purchases. The system is built with the following core components:

• Affiliate Policy Management: Configurable commission rates and invitation rules per user
• Invite Code System: Generation and management of unique invitation codes
• Referral Tracking: Automatic tracking of user registration through invite codes
• Reward Calculation: Dynamic commission calculation based on order amounts and rates
• Revenue Management: Accumulated reward tracking and withdrawal functionality

Core Features

User Invitation System

• Generate unique 8-character alphanumeric invite codes
• Maximum configurable number of active codes per user
• Automatic code deactivation and cleanup
• Referral relationship establishment during user registration

Commission & Rewards

• Configurable commission rates per user
• Trigger limits per referred user to prevent abuse
• Automatic reward calculation on order payments
• Real-time affiliate statistics tracking
• Secure withdrawal system with balance verification

Administrative Controls

• Centralized affiliate policy management
• Global configuration for default rates and limits
• Comprehensive audit trail for all affiliate activities
• Integration with user balance and order systems

Module Structure

The market module follows the standard Helium module structure:

• entities/: Database models and operations for affiliate data
• services/: Business logic processors implementing affiliate functionality
• rpc/: gRPC service implementations for client communication
• hooks/: Event listeners for user registration and order processing
• events/: Internal event definitions for reward processing
• config.rs: Module configuration structure

Integration Points

The market module integrates with several other Helium modules:

• Auth Module: Listens to user registration events to initialize affiliate policies
• Shop Module: Processes order payment events to trigger reward calculations
• Manage Module: Uses configuration system for affiliate settings
• Redis: Stores module configuration for fast access
• RabbitMQ: Event-driven communication with other modules

API Endpoints

The module exposes the following gRPC APIs:

• GetAffiliateStats: Retrieve user’s affiliate statistics and invite codes
• ListInviteCodes: List active invite codes for a user
• CreateInviteCode: Generate new invite codes
• DeleteInviteCode: Deactivate invite codes
• WithdrawAffiliateReward: Transfer earned rewards to user balance

All APIs follow the Processor pattern for consistent business logic processing [[memory:6079830]].

Database Schema

The module uses a dedicated market schema with the following tables:

• affiliate_policy: Per-user commission rates and invitation settings
• affiliate_stats: Aggregated revenue and referral statistics
• invite_code: User-generated invitation codes
• affiliate_relation: Historical record of reward transactions

Event Flow

The affiliate system operates through an event-driven architecture:

1. User Registration: When users register with an invite code, the system creates affiliate policies and establishes referral relationships
2. Order Payment: When referred users make purchases, the system calculates and awards commissions to inviters
3. Reward Processing: Affiliate rewards are processed asynchronously through internal events
4. Balance Updates: Successful withdrawals update user account balances atomically

This documentation provides developers with the necessary understanding to maintain, extend, and integrate with the market module’s affiliate functionality.