svc-reviews¶
NovaTrek Reviews Service | Support | v1.0.0 | Guest Experience Team
Manages guest reviews, ratings, and social proof for NovaTrek Adventures.
Swagger UI Download OpenAPI Spec CI/CD Pipeline Source Code Technology Stack
Delivery Status¶
Delivery Wave: 7 -- New Capabilities
| Stage | Status |
|---|---|
| Infrastructure (Bicep) |  complete |
| Database Schema (Flyway) | complete |
| Deployed to Dev | not-started |
| Smoke Tested | not-started |
| Deployed to Prod | not-started |
| Pipeline | Status |
|---|---|
| CI Pipeline | complete |
| CD Pipeline | complete |
Azure Resources (Dev):
Integration Context¶
Generated from architecture/specs/svc-reviews.yaml + cross-service-calls.yaml
Data Store¶
Entity Relationship Diagram¶
Generated from architecture/metadata/data-stores.yaml
Overview¶
| Property | Detail |
|---|---|
| Engine | PostgreSQL 15 |
| Schema | reviews |
| Tables | reviews, review_helpful_votes, rating_aggregates |
| Estimated Volume | ~500 reviews/day, ~50,000 reads/day |
| Connection Pool | min 5 / max 20 / idle timeout 5min |
| Backup Strategy | Daily pg_dump, 30-day retention |
Key Features¶
- Reservation-gated review submission (cross-ref svc-reservations)
- Optimistic locking on review records (_rev field)
- Pre-computed rating aggregates per trip and per guide
- Full-text search on review body via tsvector index
Table Reference¶
reviews¶
Guest reviews with ratings, moderation status, and optimistic locking
| Column | Type | Constraints |
|---|---|---|
review_id | UUID | PK, DEFAULT gen_random_uuid() |
reservation_id | UUID | NOT NULL, FK -> svc-reservations |
guest_id | UUID | NOT NULL |
trip_id | UUID | NOT NULL |
guide_id | UUID | NULL |
overall_rating | SMALLINT | NOT NULL, CHECK (1-5) |
safety_rating | SMALLINT | NULL, CHECK (1-5) |
guide_quality_rating | SMALLINT | NULL, CHECK (1-5) |
value_for_money_rating | SMALLINT | NULL, CHECK (1-5) |
title | VARCHAR(200) | NOT NULL |
body | TEXT | NOT NULL |
body_tsvector | TSVECTOR | Generated column for full-text search |
visit_date | DATE | NOT NULL |
moderation_status | VARCHAR(20) | NOT NULL, DEFAULT 'pending' |
helpful_count | INTEGER | NOT NULL, DEFAULT 0 |
_rev | INTEGER | NOT NULL, DEFAULT 1 (optimistic lock) |
created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() |
updated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() |
Indexes:
idx_review_tripontrip_ididx_review_guestonguest_ididx_review_guideonguide_ididx_review_body_ftsonbody_tsvector(GIN)uq_review_reservation_guestonreservation_id, guest_id(UNIQUE)
review_helpful_votes¶
Tracks which guests found a review helpful (one vote per guest per review)
| Column | Type | Constraints |
|---|---|---|
vote_id | UUID | PK, DEFAULT gen_random_uuid() |
review_id | UUID | NOT NULL, FK -> reviews |
guest_id | UUID | NOT NULL |
created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() |
Indexes:
uq_vote_review_guestonreview_id, guest_id(UNIQUE)
rating_aggregates¶
Pre-computed rating summaries per trip and per guide
| Column | Type | Constraints |
|---|---|---|
aggregate_id | UUID | PK, DEFAULT gen_random_uuid() |
entity_type | VARCHAR(10) | NOT NULL (trip or guide) |
entity_id | UUID | NOT NULL |
review_count | INTEGER | NOT NULL, DEFAULT 0 |
avg_overall | NUMERIC(3,2) | NOT NULL, DEFAULT 0 |
avg_safety | NUMERIC(3,2) | None |
avg_guide_quality | NUMERIC(3,2) | None |
avg_value_for_money | NUMERIC(3,2) | None |
last_review_at | TIMESTAMPTZ | NULL |
updated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() |
Indexes:
uq_aggregate_entityonentity_type, entity_id(UNIQUE)
Solutions Affecting This Service¶
| Ticket | Solution | Capabilities | Date |
|---|---|---|---|
| NTK-10008 | Guest Reviews and Ratings Platform | CAP-1.7, CAP-1.2 | 2026-03-06 |
Endpoints (10 total)¶
GET /reviews -- List reviews with optional filters¶
Returns paginated reviews filtered by trip, guest, guide, or rating range. Only APPROVED reviews are returned for public queries.
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.
POST /reviews -- Submit a guest review¶
Creates a review for a completed reservation. The service validates that
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.
GET /reviews/{review_id} -- Retrieve a specific review¶
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.
PATCH /reviews/{review_id} -- Update a review (guest edit or moderation action)¶
Guests may update their review text and rating while in PENDING_MODERATION status.
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.
DELETE /reviews/{review_id} -- Delete a review¶
Soft-deletes a review. Only the review author or a moderator can delete.
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.
POST /reviews/{review_id}/helpful -- Mark a review as helpful¶
Increments the helpful_count for a review. Each guest can mark a review helpful once.
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.
GET /trips/{trip_id}/rating-summary -- Get aggregated rating summary for a trip¶
Returns the average rating, total review count, and rating distribution
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.
GET /guides/{guide_id}/rating-summary -- Get aggregated rating summary for a guide¶
Returns the average rating, total review count, and rating distribution
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.
GET /moderation/queue -- List reviews pending moderation¶
Returns reviews in PENDING_MODERATION status, ordered by submission date. Requires MODERATOR role.
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.
POST /moderation/{review_id}/decide -- Approve or reject a review¶
Sets the moderation decision for a review. APPROVED reviews become publicly visible.
Generated from architecture/specs/svc-reviews.yaml Auto-generated baseline — shows standard request flow. For detailed behavioral sequences, see the relevant solution design.