Review system

Trust scores, ratings, and verified purchase reviews

Overview

Current state

No reviews or ratings, trust is based on profile info only.

Target state

  • Star ratings for sellers
  • Written reviews from buyers
  • Verified purchase badges
  • Trust score algorithm

Trust signals

  • Overall rating (1-5 stars)
  • Number of completed sales
  • Response time
  • Shipping speed
  • Account age

Features

For buyers

  • Leave review after purchase
  • Rate: item accuracy, shipping, communication
  • Add photos of received item
  • Edit review within 7 days

For sellers

  • Respond to reviews
  • See aggregate ratings
  • Trust badge levels (Bronze, Silver, Gold)
  • Display top reviews on profile

For platform

  • Review moderation
  • Fake review detection
  • Trust score calculation
  • Featured trusted sellers

Architecture

Database schema

packages/db/schema/reviews.ts
export const reviews = pgTable('reviews', {
  id: uuid('id').primaryKey().defaultRandom(),
  transactionId: uuid('transaction_id').references(() => transactions.id),
  reviewerId: uuid('reviewer_id').references(() => users.id),
  sellerId: uuid('seller_id').references(() => users.id),
  itemId: uuid('item_id').references(() => items.id),

  overallRating: integer('overall_rating').notNull(), // 1-5
  itemAccuracyRating: integer('item_accuracy_rating'),
  shippingRating: integer('shipping_rating'),
  communicationRating: integer('communication_rating'),

  comment: text('comment'),
  photos: jsonb('photos').$type<string[]>(),

  sellerResponse: text('seller_response'),
  sellerRespondedAt: timestamp('seller_responded_at'),

  isVerifiedPurchase: boolean('is_verified_purchase').default(true),
  createdAt: timestamp('created_at').defaultNow(),
});
packages/db/schema/seller-stats.ts
export const sellerStats = pgTable('seller_stats', {
  sellerId: uuid('seller_id').primaryKey().references(() => users.id),
  totalReviews: integer('total_reviews').default(0),
  averageRating: decimal('average_rating', { precision: 2, scale: 1 }),
  totalSales: integer('total_sales').default(0),
  avgResponseTime: integer('avg_response_time'), // minutes
  avgShipTime: integer('avg_ship_time'), // hours
  trustScore: integer('trust_score').default(0), // 0-100
});

Trust score algorithm

packages/features/reviews/trust-score.ts
function calculateTrustScore(seller: SellerStats): number {
  let score = 0;

  // Rating weight (40%)
  if (seller.averageRating) {
    score += (seller.averageRating / 5) * 40;
  }

  // Sales volume (25%)
  const salesScore = Math.min(seller.totalSales / 100, 1) * 25;
  score += salesScore;

  // Response time (15%)
  if (seller.avgResponseTime < 60) score += 15;
  else if (seller.avgResponseTime < 240) score += 10;
  else if (seller.avgResponseTime < 1440) score += 5;

  // Shipping speed (15%)
  if (seller.avgShipTime < 24) score += 15;
  else if (seller.avgShipTime < 48) score += 10;
  else if (seller.avgShipTime < 72) score += 5;

  // Account age (5%)
  const accountAgeMonths = getAccountAgeMonths(seller.userId);
  score += Math.min(accountAgeMonths / 12, 1) * 5;

  return Math.round(score);
}

Review submission

packages/features/reviews/actions/submit.ts
async function submitReview(data: ReviewInput) {
  // Verify purchase
  const transaction = await db.query.transactions.findFirst({
    where: and(
      eq(transactions.id, data.transactionId),
      eq(transactions.buyerId, data.reviewerId),
      eq(transactions.status, 'completed'),
    ),
  });

  if (!transaction) throw new Error('Invalid transaction');

  // Create review
  const review = await db.insert(reviews).values({
    ...data,
    isVerifiedPurchase: true,
  }).returning();

  // Update seller stats
  await updateSellerStats(transaction.sellerId);

  return review;
}

Implementation

Basic reviews

Build review submission after purchase, star ratings display, and seller profile reviews section.

Trust score

Calculate and display trust score, badge levels (Bronze/Silver/Gold), and trust indicators on listings.

Moderation

Add report inappropriate reviews, admin moderation queue, and fake review detection.

Advanced features

Implement review photos, seller responses, and review analytics.

Checklist

Database

  • Reviews table
  • Seller stats materialized view
  • Trust score calculation trigger

Features

  • Review submission form
  • Star rating component
  • Seller profile reviews section
  • Trust badge display

Moderation

  • Report review flow
  • Admin moderation panel
  • Fake review detection

Notifications

  • Email when review received
  • Push notification for new review
  • Reminder to leave review