Review System

Overview

PinTeach supports reviews from two sources:

• PinTeach: Students submit reviews via in-app prompts after sessions
• External: Teachers import from Preply, Italki, Verbling, Google Business, Trustpilot

Review Data Model

reviews

Field	Type	Description
rating	integer	1-5 stars (required)
title	varchar	Optional title
body	text	Review content
quickTags	jsonb	Tag array (e.g., “patient”, “fun”)
source	enum	pinteach, preply, italki, etc.
status	enum	pending, approved, hidden, flagged
isFeatured	boolean	Highlighted on profile
isAnonymous	boolean	Student identity hidden
teacherResponse	text	Public teacher reply

Review Requests

review_requests — Solicitation system with channels:

• in_app: Shown in student portal
• email: Sent via email
• link: Shareable review link

Token-based verification with expiration.

Teacher Dashboard

/teacher/reviews has 5 tabs:

1. Overview: KPIs + rating distribution + recent reviews
2. All: Full list with search + status/source filters
3. Requests: Send review solicitations to students
4. Import: Import external reviews from other platforms
5. Settings: Moderation and display preferences

Actions

Action	Description
Approve	Move from pending → approved
Hide	Move to hidden (not visible publicly)
Feature	Highlight on teacher profile
Respond	Add public teacher response
Delete	Remove review entirely

Review Settings

Per-teacher config (review_settings, 1:1):

Setting	Default	Description
autoRequestEnabled	false	Auto-send request after sessions
autoApprove	true	Auto-approve new reviews
minAutoApproveRating	3	Min rating for auto-approve
showOnProfile	true	Display reviews on profile
notifyOnNewReview	true	Email on new review

Embeddable Widgets

The Widget System supports reviews widgets with 4 layouts:

• Grid: Card grid layout
• Carousel: Horizontal slider
• List: Vertical list
• Wall: Masonry wall

Configurable: accent color, max reviews, min rating, sort order, show/hide fields.

Embed via iframe with postMessage resize support.

Public Reviews Endpoint

GET /public/:slug/reviews — Returns approved reviews for a teacher’s public profile and widgets.

Query Parameters

Parameter	Type	Default	Description
rating	integer	—	Filter by star rating (1-5)
source	string	—	Filter by review source
dateFrom	string (ISO date)	—	Filter reviews created on or after this date
dateTo	string (ISO date)	—	Filter reviews created on or before this date
sortBy	string	createdAt	Sort field
page	integer	1	Page number
limit	integer	10	Results per page

All parameters are optional. dateFrom and dateTo accept ISO date strings and work alongside the other filters.

Student Review Flow

1. Student completes a session
2. Review request appears (if auto-request enabled, after configurable delay)
3. Student rates (1-5 stars) + optional quickTags + body text
4. Review submitted with status based on settings (pending or approved)
5. Teacher gets notification (if enabled)