# Kevron Suites & Apartments — Reviews & Testimonials System Implementation Notes

This document provides a technical guide to the architecture, database schema, Filament admin resources, front-end views, security measures, and testing suites developed for the public **Reviews and Testimonials Page** at `/reviews` for Kevron Suites and Apartments.

---

## 1. Core Architectural Strategy

We have developed a robust, secure, and authenticated stays reviews system designed to enhance guest trust, prevent artificial seeding, protect personal data, and allow rich evaluations of key stay profiles.

```mermaid
graph TD
    subgraph Frontend Submissions Hub
        Form[Guest Form /reviews] -->|Submits stay feedback| Controller[ReviewsController@submit]
        Ref[Booking Reference] -->|Optional check| Booking[Verify Booking checked_out]
    end

    subgraph Database Storage (IP / Spam Protection)
        Controller -->|Store pending status| DB[(Database reviews)]
        Controller -->|Optional media upload| Media[(Database review_media)]
    end

    subgraph Admin Moderation Panel (Filament)
        DB -->|Review status = pending| Filament[ReviewResource]
        Filament -->|Admin Approve status = approved| PublicFeed[Public Approved Reviews]
        Filament -->|Add Response| Response[ReviewResponseResource]
    end

    subgraph Public View Page (/reviews)
        PublicFeed -->|Calculates overall score| index[index.blade.php]
        PublicFeed -->|Calculates category averages| index
        Response -->|Inline management replies| index
    end
```

---

## 2. Database Schema and Models

The migration `2026_06_01_150000_create_reviews_system_tables.php` defines a modular schema:

### 2.1 Schema Definition
- **`review_categories`**: Mapped categories (Cleanliness, Comfort, Location, Security, Service, Value) with custom icon metadata.
- **`review_sources`**: Channels mapping (Website Review, Google Review, Direct Feedback).
- **`reviews`**: Recreated table with stay profile metrics (`stay_type`), verified stayed status (`is_verified_stay`), featured status (`is_featured`), overall score, comment headers, and moderation tracking (`status`, `moderation_notes`, `published_at`).
- **`review_category_ratings`**: Granular scores (1-5) for each category attached to a review.
- **`review_responses`**: Management responses linked 1-to-1 with reviews.
- **`review_media`**: Pivots to `media_assets` with separate media approved markers.
- **`video_testimonials`**: Separate curated guest experience reels with captions/transcripts.
- **`google_review_integrations`**: Fallback cache structure for Google profile integrations.
- **`review_helpful_votes` & `review_reports`**: Anonymous telemetry logging tracks upvotes/spam flags from distinct IP addresses.

### 2.2 Eloquent Models
- **`Review.php`**: Casts `overall_rating` to integer and holds relationships to `ApartmentType`, `Location`, `ReviewSource`, `ReviewCategoryRating`, `ReviewResponse`, `ReviewMedia`, `ReviewHelpfulVote`, and `ReviewReport`.
- **`ReviewCategory.php`**: Mapped to `ReviewCategoryRating` for progress bars.
- **`ReviewSource.php`**: Maps reviews channels.
- **`ReviewCategoryRating.php`**, **`ReviewResponse.php`**, **`ReviewMedia.php`**, **`VideoTestimonial.php`**, **`GoogleReviewIntegration.php`**, **`ReviewHelpfulVote.php`**, **`ReviewReport.php`**, **`ReviewModerationLog.php`** created successfully.

---

## 3. Database Seeding

Idempotent `ReviewsSeeder.php` seeds essential page dependencies:
1. **Categories**: Cleanliness, Comfort, Location, Security, Service, Value.
2. **Sources**: Website, Google, Direct.
3. **FAQs**: Seeding 8 custom-curated questions answering reviews integrity, verification, rating categories, video guidelines, and display initials privacy.
4. **SEO/Schema**: polymorphic metadata records for `ReviewsPage`.

---

## 4. Filament Admin Panel CRUDs

Registered resources inside the `/admin` portal (using Filament v3 signatures):
1. **`ReviewResource`**: Re-engineered form with complete section grids (Guest stays, category ratings, source channels, and administrative moderation toggles).
2. **`ReviewCategoryResource`**: Custom icons and slugs mapping.
3. **`ReviewResponseResource`**: Connects professional management replies to reviews.
4. **`VideoTestimonialResource`**: Video URL and thumbnail path control with transcript options.
5. **`GoogleReviewIntegrationResource`**: Caches and updates Google profile reviews.
6. **`ReviewReportResource`**: Allows auditing reviews flagged for spam or language violations.

---

## 5. Public Controller and Frontend Layout

### 5.1 `ReviewsController.php`
- **`index`**: Compiles total count, overall score averages, star rating distributions, and category-by-category ratings ( Cleanliness to Value). Supports active query string filtering by stars, stay type, apartment type, and channel source, along with sorting parameters (Newest, Highest rated, Most helpful).
- **`submit`**: Implements validations, duplicate checking per booking reference, stay verification badges (against checkout booking status), category ratings loops, secure media upload MIME/size limits, and Low Rating administrative warnings.
- **`helpful` & `report`**: AJAX telemetry endpoints logging votes and spam reports, guarded against duplicate IP submissions.

### 5.2 `reviews/index.blade.php`
A custom-engineered Blade template that strictly implements all design constraints:
- **Typography Caps**: Headings use Marcellus font with clamp caps (H1 max `1.8rem`, H2-H6 max `1.5rem`), body and labels use Inter (max `0.875rem`).
- **Pills Radius**: All button contours enforce `border-radius: 50px` with transitions and slow bouncy scales on hover.
- **Cards Radius**: Review blocks, filters, FAQ accordions, and CTA cards enforce flat `border-radius: 0.1rem` with thin `box-shadow` offsets, deepening backgrounds on hover.
- **Visual Grid**: Displays dynamic aggregate panels, category progress indicators, featured sliders, reviews grid filters, video reels, Google configurations fallback, submission forms with interactive star ratings, crawlable SEO paragraph, and interactive Alpine.js FAQ accordions.
- **Escaped Directives**: JSON-LD scripts use `@@context` and `@@type` to bypass Blade directive compilers.

---

## 6. Security and Privacy Guidelines
- **Email/Phone Privacy**: Contact emails, phones, and booking references are never displayed publicly.
- **Public Initials**: Supports initials-only formatting (`display_name`) to safeguard personal profiles.
- **Duplicate Protection**: Blocks duplicate submissions for identical booking references.
- **Sanitisation**: Validates comment length, types, and restricts file formats (JPG, PNG, WEBP, MP4) up to a 20MB limit.
- **Rate-Limiting**: Logs all activities and protects telemetry endpoints from repeat upvoting.

---

## 7. Automated Verification Suite

Added `tests/Feature/ReviewsPageTest.php` to verify routing:
- **Route Loads**: Asserts 200 index code.
- **Global Header/Footer**: Asserts logo and Regina Coker addresses remain present.
- **Empty States**: Renders reviews coming soon text cleanly when no approved records exist.
- **Moderation Visibility**: Approved reviews appear, pending and rejected stay hidden.
- **Submissions & Duplications**: Asserts form validation, database stores as pending, and duplicate booking reference attempts fail.
- **Integrations Fallback**: Renders Google settings placeholder cleanly.
- **SEO Canonical & Schema**: Asserts canonical routes and parsed schemas.

All 10 tests passed successfully.