Ratings & Referrals
Relevant source files
The following files were used as context for generating this wiki page:
The Ratings & Referrals system is a critical component of the Subito platform designed to maintain service quality and drive user growth. The Ratings module allows customers to provide feedback on completed bookings, which directly influences partner match scores and platform trust. The Referrals module facilitates organic growth through a structured reward system, utilizing referral codes and virtual credits to incentivize both referrers and new users.
These systems interact closely with the Bookings and Users modules to trigger rewards and calculate partner performance metrics. Sources: packages/db/src/schema/ratings.ts, packages/db/src/schema/referrals.ts, packages/shared/src/utils/index.ts:38-48
Ratings System Architecture
The Ratings system captures multi-dimensional feedback from customers regarding their experience with service partners. Ratings are linked to specific bookings and include numerical scores, qualitative comments, and categorical tags.
Data Model: Ratings
The ratings table stores detailed feedback, including specific metrics for service quality and professionalism.
| Field | Type | Description |
|---|---|---|
id | UUID | Primary key. |
booking_id | UUID | Reference to the associated booking. |
user_id | UUID | The customer providing the rating. |
partner_id | UUID | The partner being rated. |
rating | Integer | Overall numerical score. |
service_quality | Integer | Specific score for quality of work. |
punctuality | Integer | Score for timing. |
professionalism | Integer | Score for behavior. |
status | Enum | PENDING, SUBMITTED, or DISCARDED. |
Sources: packages/db/src/schema/ratings.ts:21-46, packages/db/drizzle/0000_normal_the_order.sql:415-437
Partner Match Scoring Logic
Ratings are not purely informational; they are programmatically used to influence the assignment of future bookings. The calculatePartnerMatchScore utility uses a partner's average rating as a primary weight in the matching algorithm.
export function calculatePartnerMatchScore(input: {
averageRating: string | null
completedBookings: number | null
distanceKm: number
}): number {
const rating = input.averageRating ? parseFloat(input.averageRating) : 3
const completed = input.completedBookings || 0
const distanceScore = Math.max(0, 10 - input.distanceKm)
return rating * 2 + Math.min(completed / 10, 3) + distanceScore * 0.5
}
Sources: packages/shared/src/utils/index.ts:38-48
Referrals & Credits System
The Referral system manages the generation, usage, and reward distribution of user-specific referral codes. It employs a two-sided incentive model where both the referrer and the referee receive rewards upon a successful transaction.
Referral Lifecycle
The referral process involves code generation, application during new user onboarding, and reward triggering upon a specific event (usually a completed booking).
This diagram illustrates the flow from code creation to reward distribution based on trigger events. Sources: packages/db/src/schema/referrals.ts:46-73, packages/db/src/seed.ts:1097-1112
Referral Data Structures
The referral system is supported by three primary tables: referral_codes, referral_rewards, and user_credits.
Referral Codes
Stores the configuration for a user's unique code, including reward amounts and usage limits.
Sources: packages/db/src/schema/referrals.ts:21-36
Referral Rewards
Tracks individual reward instances and their statuses (e.g., PENDING, CREDITED).
Sources: packages/db/src/schema/referrals.ts:46-73
User Credits & Transactions
Manages the virtual wallet for each user, recording every instance of credits earned or used.
Sources: packages/db/src/schema/referrals.ts:75-115
Credit Transaction Types
Transactions are categorized to maintain a clear audit trail of user balances:
- EARNED: Credits added via referrals or promotions.
- USED: Credits applied to discount a booking.
- REFUNDED: Credits returned after a booking cancellation.
- EXPIRED/ADJUSTED: Administrative or time-based balance changes.
Sources: packages/db/src/schema/referrals.ts:89-95, packages/db/drizzle/0000_normal_the_order.sql:24-24
System Relationships
The following Entity-Relationship diagram showcases how Ratings and Referrals integrate with the core User and Booking modules.
The diagram visualizes the primary keys and foreign key relationships defined in the schema files. Sources: packages/db/src/schema/ratings.ts:48-61, packages/db/src/schema/referrals.ts:117-156
Summary
The Ratings & Referrals system serves as a dual-purpose engine for quality control and acquisition. By quantifying partner performance through the Ratings module, the platform ensures high service standards. Concurrently, the Referrals and Credits module provides a robust framework for user incentivization, managed through a strictly audited transaction ledger. Together, they form the socio-economic backbone of the Subito marketplace.