Reviews and ratings

Star ratings with words and photos about anything: services, products, places, games, mini-apps, people, a collection's records. Part of the Spaces engine. Code: convex/kits/reviews/ (server and settings), src/kits/reviews/ (blocks), tests in tests/reviews.test.ts.

A board is a setting #

blueprint.reviews is an object of review boards by id. The Reviews kit adds board reviews; the AI or the owner can add more (a menu board and a staff board).

"reviews": {
  "reviews": {
    "name": "Reviews",
    "subjects": [{ "id": "cut", "name": "Haircut" }, { "id": "colour", "name": "Colour" }],
    "aspects": [{ "id": "value", "name": "Value" }, { "id": "friendly", "name": "Friendly" }],
    "writers": ["member", "visitor"],
    "verified": ["booked", "badge:verified"],
    "managers": false,
    "photos": 4
  }
}

Setting	What it does	Default
`name`	The board's name	required
`scale`	Stars, 3 to 10	5
`icon`	What a star is: an emoji (★ ❤️ 🔥) or an icon name	★
`subjects`	Things to pick when writing: `[{ id, name, about? }]`	none
`subjectsFrom`	A collection whose records are the things to review (`record:<id>`)	none
`aspects`	Up to 6 parts rated on their own: `[{ id, name }]`	none
`writers`	Who may write: role ids, `member`, `level:<id>`, `level:<id>+`, `badge:<id>`	roles that can post or add
`verified`	Whose reviews get the Verified mark: same tokens plus `booked` (has a booking here)	none
`managers`	Whether people who manage may review their own space	true
`text`	`off`, `optional` (stars alone are fine) or `required`	optional
`minLength`, `maxLength`	Characters	0, 2000
`titles`	A one-line title	false
`photos`	Photos per review, 0 to 10	4
`approval`	New and edited reviews wait for someone who manages	false
`replyRoles`	Who may answer in public; `[]` = nobody	people who manage
`helpful`	Helpful / not helpful votes	true
`reports`	Reporting	true
`hideAfter`	Reports before a review hides itself until checked	3
`perDay`	Reviews one person may write per day on the board	10
`links`	Links in reviews (blocked by default: mostly spam)	false
`edit`	People can change their review	true

Every word is a setting: blueprint.words["reviews.<key>"] (keys in REVIEW_WORDS, convex/kits/reviews/model.ts).

Subjects #

Every review is about a subject, and each person writes one review per subject (writing again changes it). A subject is one of:

an id from the board's subjects list,
record:<id>, a record of the board's subjectsFrom collection,
any short id a visible block names (app:weather, game:trivia, @handle for a person),
main, the board as a whole, when the board has no list.

So putting reviews.stars with a new subject on a page is all it takes to make that thing reviewable. Anything else is refused, so nobody can fill the database with made-up subjects. People can't review themselves (@handle).

Blocks #

Block	What it shows
`reviews.summary`	Average in big stars, count, a bar per star (tap to read those), aspect averages, Write a review
`reviews.list`	Reviews with sort (most helpful, newest, highest, lowest) and filters (stars, with photos, verified); your own first
`reviews.stars`	A small ★ 4.6 (128) line that opens the reviews in a sheet; hidden until the first review unless `empty` is set
`reviews.write`	A "How was it?" card with stars to tap; shows your review once written
`reviews.top`	The board's subjects ranked by rating or by how many reviews
`reviews.queue`	Waiting and reported reviews, to approve, hide or keep (people who manage only)

Inside every review: avatar and name, the Verified mark, stars, aspects, title, words (Read more), photos full screen, helpful votes, the owner's answer, report (spam, offensive, fake, off topic, something else), edit and delete your own, hide and approve for people who manage.

Who sees what #

A board whose every block is hidden from a person (visibleTo, levels, badges) is hidden on the server too, like collections and feeds.
Only live reviews show and count. Pending and hidden ones are seen by their writer and by people who manage.
Reviews that hit hideAfter reports hide themselves and go to the queue. Editing doesn't bring them back; Keep does (and clears the reports).
With approval, edits go back to waiting, so a review can't be swapped after approval.

AI tools (MCP, API keys, in-app AI) #

Boards, blocks and pages are built like everything else: add_kit reviews, or propose_change on /reviews and pages, approved by a person. Reading and acting on reviews are builder tools (convex/lib/capabilities/tools.ts, run in convex/capabilities/run.ts):

Tool	Scope	What it does
`list_reviews`	data.read	Totals and reviews of a board or subject; status live, pending, hidden or reported
`answer_review`	data.write	The space's public answer under a review (empty takes it away)
`moderate_review`	data.write	approve, hide or keep a review

All need the manage permission. There is no tool that writes a review on purpose: reviews come from people, so an AI or an API key can never fake one.

Light on the device #

A summary or a star line reads one totals row (reviewStats), however many reviews there are.
Lists load a page at a time (Convex pagination) with indexes for each sort and star filter.
Photos upload to the media library folder reviews and go with the review when it's deleted.

Recipes #

Services page: a board with the services as subjects, reviews.summary + reviews.list with subject *, and reviews.stars under each service with its subject.
Product catalog: subjectsFrom the products collection, plus reviews.top.
Games or mini-apps: subjects game:<id> / app:<id> and a reviews.stars next to each.
A coach or tutor: subject @handle, writers: ["member"], verified: ["booked"].
A business: managers: false so the owner can't review their own business.