Ratings & Reviews

Trust is everything in a peer-to-peer marketplace. Our rating system helps buyers find reliable sellers and helps sellers identify trustworthy buyers. We use a “simultaneous reveal” approach inspired by Airbnb — neither party sees the other’s review until both have submitted (or the deadline passes).

Why Simultaneous Reveal?

Traditional review systems have a problem: if you can see the other person’s review before writing yours, you might:

• Retaliate with a bad review because they gave you one
• Reciprocate with a good review hoping they’ll do the same
• Game the timing to see their review first

Our simultaneous reveal system prevents all of this. Reviews are hidden until both are submitted or the deadline passes, encouraging honest feedback.

Review Window Lifecycle

Every completed order gets a 7-day review window. Here’s how it works:

Reveal Timing

Auto-Submission Defaults

When a review is auto-generated, we use these default values:

The 5-star default assumes good faith — if neither party complained, the transaction presumably went well.

Background Processing

Expired review windows are processed by a background job:

1. EventBridge Scheduler triggers an hourly message to the process-expired-reviews SQS queue
2. The handler queries for reviews where deadline < now and revealedAt = null
3. For each expired review, autoCompleteAndReveal() is called
4. Missing reviews are filled with defaults using an atomic MongoDB $ifNull operation
5. Reviews are revealed and rating stats are updated

This ensures reviews are processed within an hour of their deadline, even under high load.

What Gets Reviewed

Buyers and sellers rate different things, reflecting their different roles in the transaction.

The Review Flow

Both parties follow the same basic flow — rate, optionally comment, submit, then wait for the other party (or the deadline):

The key difference is what each party rates:

• Buyers rate three categories (accuracy, packaging, communication) + optional comment
• Sellers rate one overall score + optional comment

Once both submit (or the 7-day deadline passes with missing reviews auto-filled), reviews are revealed simultaneously.

Rating Aggregation

When reviews are revealed, we update the user’s aggregated rating stats incrementally:

• Seller stats: We add the new accuracy, packaging, and communication ratings to their running sums and recalculate averages. The overall score is the average of the three category averages.
• Buyer stats: We add the new rating to the running sum and recalculate the average.

The UserRatingStats Model

Here’s what we store for each user:

interface UserRatingStats {
  userId: string
 
  seller?: {
    accuracy: { sum: number; count: number; avg: number }
    packaging: { sum: number; count: number; avg: number }
    communication: { sum: number; count: number; avg: number }
    overall: { sum: number; count: number; avg: number }
  }
 
  buyer?: {
    sum: number
    count: number
    avg: number
  }
 
  lastUpdatedAt: Date
}

Which Orders Get Review Windows?

Not all orders can be reviewed. Review windows are created only for orders that actually completed (items changed hands):

Displaying Ratings

On Seller Profiles

When someone views a seller’s profile, they see:

Example: “4.8 stars (234 reviews) — Accuracy: 4.9, Packaging: 4.7, Communication: 4.8”

On Buyer Profiles

Buyers have simpler stats:

Example: “4.9 stars (42 reviews)“

Edge Cases

API Endpoints

Code Locations