Skip to main content

​
Reviews & Ratings

The reviews and ratings system is essential for building trust and credibility in the Kin Conecta platform. It allows tourists to share their experiences and helps future travelers make informed decisions when choosing local guides.
Reviews are linked to completed tours and can only be written by tourists who have actually experienced the tour with a specific guide.

​
System Overview

The review system captures detailed feedback about tour experiences, including numerical ratings and written comments.

Star Ratings

Numerical ratings on a scale that contribute to guide’s average rating score.

Written Reviews

Detailed feedback about the tour experience, guide performance, and overall satisfaction.

Review Replies

Guides can respond to reviews, addressing feedback and building relationships.

Social Engagement

Reviews can receive likes from other users, highlighting helpful feedback.

​
Review Structure

Each review contains comprehensive information about the tour experience: 
{
  "reviewId": 123,
  "tripId": 456,
  "tourId": 789,
  "guideId": 12,
  "touristId": 34,
  "rating": 5,
  "comment": "¡Experiencia increíble! Ana fue una guía excepcional, muy conocedora de la historia de la CDMX. El tour gastronómico superó todas mis expectativas. Totalmente recomendado.",
  "likesCount": 8,
  "repliesCount": 1,
  "createdAt": "2026-03-05T18:30:00",
  "updatedAt": "2026-03-05T18:30:00"
}

​
Field Descriptions

Unique identifier for the review. Auto-generated by the system.
Reference to the specific trip instance. Links the review to an actual completed tour experience.
Reference to the tour package that was booked. Used for aggregating reviews per tour type.
The ID of the guide being reviewed. Used to calculate guide’s average rating and display on their profile.
The ID of the tourist who wrote the review. Ensures accountability and prevents duplicate reviews.
Numerical rating score. Typically on a scale (e.g., 1-5 stars) representing overall satisfaction.
Written feedback about the tour experience. Can include details about the guide’s knowledge, tour quality, organization, and overall experience.
Number of likes the review has received from other users. Helps highlight helpful reviews.
Number of replies to the review (typically from the guide). Indicates active guide engagement.
Timestamps for review creation and last update. Allows tourists to edit reviews within a reasonable timeframe.

​
API Endpoints

The review system provides endpoints for CRUD operations:

​
Get All Reviews

GET /api/reviews
Retrieves all reviews in the system. Useful for displaying recent reviews on homepage or analytics.

​
Get Review by ID

GET /api/reviews/{id}
Retrieves a specific review with all details including replies and engagement metrics.

​
Create Review

POST /api/reviews
Content-Type: application/json

{
  "tripId": 456,
  "tourId": 789,
  "guideId": 12,
  "touristId": 34,
  "rating": 5,
  "comment": "Amazing experience!"
}
Creates a new review after a completed tour.

​
Update Review

PUT /api/reviews/{id}
Content-Type: application/json

{
  "rating": 5,
  "comment": "Updated review text..."
}
Allows tourists to edit their reviews (typically within a limited timeframe).

​
Delete Review

DELETE /api/reviews/{id}
Soft deletes a review (sets deletedAt timestamp) rather than permanently removing it.
Review deletion should be restricted to prevent abuse. Typically only allowed within a short window after posting or by administrators.

​
Rating Calculation

Guide ratings are calculated and stored in the guide_profiles table: 
@Column(name = "rating_avg")
private BigDecimal ratingAvg;

@Column(name = "reviews_count")
private Integer reviewsCount;

​
Average Rating Formula

rating_avg = SUM(all_ratings) / COUNT(reviews)
This average is updated whenever a new review is added, updated, or deleted.
The average rating is displayed prominently on guide profiles and in matching results, making it a crucial trust signal for tourists.

​
Review Replies

Guides can respond to reviews through the reply system:

​
Reply Structure

{
  "replyId": 789,
  "reviewId": 123,
  "guideId": 12,
  "body": "¡Muchas gracias por tu reseña! Fue un placer compartir la gastronomía de CDMX contigo. Espero verte en un próximo tour.",
  "createdAt": "2026-03-06T10:00:00"
}

​
Reply Endpoints

The system includes a dedicated ReviewReplyController and ReviewReplyService for managing guide responses: 
socialNetwork/src/main/java/org/generation/socialNetwork/reviews/controller/ReviewReplyController.java
socialNetwork/src/main/java/org/generation/socialNetwork/reviews/service/ReviewReplyService.java

​
User Experience Flow

1

Complete Tour

Tourist completes a tour with a guide. The system recognizes the trip as completed.
2

Review Prompt

After the tour, the tourist receives a prompt (via email or notification) to write a review.
3

Write Review

Tourist accesses the review form, selects a rating, and writes their feedback about the experience.
4

Submit & Display

Review is submitted and immediately displayed on the guide’s profile, contributing to their average rating.
5

Guide Response

Guide receives notification of the new review and can optionally write a reply thanking the tourist or addressing feedback.
6

Community Engagement

Other users can read the review and mark it as helpful (like), increasing its visibility.

​
Review Display

Reviews are displayed in multiple locations throughout the platform:

Guide Profiles

All reviews for a guide are displayed on their profile page, sorted by date or helpfulness.

Tour Pages

Reviews specific to a tour package are shown on the tour detail page.

Matching Results

Average rating and review count appear in matching recommendation cards.

Dashboard Pages

Both tourists and guides have dashboard sections dedicated to managing reviews.

​
Frontend Implementation

The platform includes dedicated dashboard pages for reviews:

​
Tourist Dashboard

frontend/src/pages/Dashboard/turista/reviewsTourist.html
frontend/src/scripts/pages/tourist/dashboard-reviews.js
frontend/src/styles/pages/tourist/dashboard-reviews.css
Allows tourists to view and manage their submitted reviews.

​
Guide Dashboard

frontend/src/pages/Dashboard/guia/reviewsGuide.html
frontend/src/scripts/pages/guide/dashboard-reviews.js
frontend/src/styles/pages/guide/dashboard-reviews.css
Enables guides to view reviews they’ve received and respond to them.

​
Best Practices

​
For Tourists

Be Specific

Provide detailed feedback about what made the experience great (or not) to help other tourists and guides improve.

Be Fair

Consider the overall experience and rate accordingly. Minor issues shouldn’t necessarily result in a 1-star review.

Be Timely

Write reviews soon after the tour while the experience is fresh in your mind.

Be Respectful

Provide constructive feedback rather than personal attacks. Focus on the experience.

​
For Guides

Respond Professionally

Reply to reviews with gratitude and professionalism, even if the feedback is critical.

Address Concerns

If a review mentions issues, acknowledge them and explain how you’re improving.

Show Appreciation

Thank tourists for positive reviews and express interest in seeing them again.

Don't Take It Personally

Use criticism as an opportunity to improve your service rather than a personal attack.

​
Trust & Safety

The review system includes safeguards to maintain integrity:
  • Reviews can only be written for completed, verified tours
  • One review per tourist per tour instance
  • Suspicious patterns (fake reviews) are monitored
  • Abusive reviews can be reported and reviewed by moderators

​
Implementation Details

The review system is implemented with:

​
Core Components

socialNetwork/src/main/java/org/generation/socialNetwork/reviews/
├── controller/
│   ├── ReviewController.java
│   └── ReviewReplyController.java
├── model/
│   └── Review.java
├── repository/
│   ├── ReviewRepository.java
│   └── ReviewReplyRepository.java
└── service/
    ├── ReviewService.java
    └── ReviewReplyService.java

​
Database Schema

CREATE TABLE reviews (
  review_id BIGINT PRIMARY KEY AUTO_INCREMENT,
  trip_id BIGINT NOT NULL,
  tour_id BIGINT NOT NULL,
  guide_id BIGINT NOT NULL,
  tourist_id BIGINT NOT NULL,
  rating SMALLINT NOT NULL,
  comment TEXT,
  likes_count INT DEFAULT 0,
  replies_count INT DEFAULT 0,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  deleted_at DATETIME NULL,
  INDEX idx_guide (guide_id),
  INDEX idx_tourist (tourist_id),
  INDEX idx_tour (tour_id)
);

​
Future Enhancements

Planned improvements to the review system:
  • Multi-Criteria Ratings: Separate ratings for knowledge, communication, organization, value, etc.
  • Photo/Video Reviews: Allow tourists to upload media with their reviews
  • Verified Reviews Badge: Special badge for verified completed tours
  • Review Moderation: AI-powered moderation to detect inappropriate content
  • Review Analytics: Dashboard for guides to track review trends and sentiment
  • Helpful Review Sorting: Algorithm to surface most helpful reviews
  • Response Rate Tracking: Display guide’s response rate and speed
  • Review Reminders: Automated reminders for tourists to leave reviews

Related Documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us