Reviews and ratings - the average that must not be gamed

Why this design

A star rating looks like an AVG() and is really a small ledger: a sum, a count and a histogram per product, maintained by deltas as reviews enter and leave the set that counts - and that set is defended, because every seller and competitor has a reason to change it. Interviewers use it to test write-time aggregation, idempotent event application, and whether you put moderation BEFORE the number rather than after.

What you will learn

• Why "4.6 from 12,408" is two integers read from one row, not 12,408 rows averaged on every view.
• Why a new review is PENDING and only PUBLISHED reviews move the aggregate.
• Why the trust scorer is a fan-out over four signals and answers publish, hold or reject.
• Why each delta carries a per-product sequence number, so it applies exactly once.
• Why a nightly recount exists, and what it can and cannot repair.
• Why ranking uses a Bayesian average, so a product with one five-star review does not outrank one with 12,408 at 4.6.

How to read this board

1. Press play once: the walkthrough follows one review from submit to the number on the page.
2. WRITE: verify, score, hold or publish.
3. AGGREGATE: state changes become deltas on one row per product.
4. READ: the page and search ranking both read that row and nothing else.
5. DATA MODEL: reviews with the star value they currently contribute, and the aggregate row.
6. Then pages 1 to 6 in order: requirements, capacity, storage, availability, how it works, deployment.

A shopper wants a number they can trust in under a second. A seller wants that number to go up. The system's job is the first one despite the second.

Ask these before designing

• Who may review? Anyone, or only buyers? "Verified purchase" is usually a badge and a trust signal, not a gate - gating loses gifts, in-store purchases and returns.
• How fast must a review appear? Seconds for most is expected. A minority held for hours is the price of not publishing fakes.
• Can reviews be edited? Yes - and an edit from 5 to 2 stars must move the aggregate by -3, exactly once.
• What does the page show: mean, histogram, or both? Both, and search ranks on something else (a Bayesian average).
• What happens when fraud is found later? Reviews are removed and the aggregate is corrected. Is the history of the rating kept?

Functional

• Submit one review per user per product: 1-5 stars, title, text, optional photos.
• Score every review for trust; publish, hold for a human, or reject.
• Show the rating, the count and a five-bar histogram on every product page.
• Show the top reviews sorted by helpfulness; users vote helpful.
• Edit and delete your own review; moderators remove reviews.
• Rank search results by a rating that resists small samples.

Non-functional

• Product page rating read p99 under 20 ms, at 70,000 page views/s peak.
• 85% of reviews published within 10 s of submit; held reviews decided within 24 h.
• Aggregate exactly right after the nightly recount, and never more than 0.5% of count off before it.
• Every state change applied to the aggregate exactly once.
• Read availability 99.99%: a page without stars converts measurably worse.

Out of scope

Q&A, seller responses, photo moderation models, review syndication between sites, incentivised review programmes.