# Kevron Suites and Apartments - Compare Apartments Page Implementation Notes

This document provides a comprehensive overview of the design architecture, database structures, admin configuration details, and user interaction mechanics built for the Compare Apartments page (`/compare-apartments`) of Kevron Suites and Apartments.

---

## 1. Core Architecture and Business Value

The Compare Apartments Page is a dynamic, database-driven decision-support tool. It helps visitors evaluate Kevron's 1, 2, 3, and 4 bedroom luxury serviced apartments in Adeniyi Jones, Ikeja, based on pricing, occupancy rules, best-use suitability, and high-fidelity amenities comparisons. 

### Key Business Goals Met
* **Optimized Group Booking Funnel:** Visitors can visually compare layout metrics in a side-by-side table on desktop and compact card list on mobile.
* **Instant Conversions:** CTAs link directly to the booking funnel with pre-filled context (`/booking?type=slug`) and direct WhatsApp reservation templates.
* **Interactivestay-persona Questionnaire:** The "Ask for Recommendation" Alpine-AJAX wizard processes guest capacity, budget, stay duration, and purpose parameters to suggest the ideal apartment with a direct booking shortcut.
* **Administrative Flexibility:** All comparison fields, values, comparison FAQs, sitemaps, and SEO schemas are dynamic and manageable directly from the Filament Admin Dashboard.

---

## 2. Database Schema and Relations

To support this dynamic, scalable setup, the following schema tables and models were registered:

```mermaid
erDiagram
    apartment_types ||--o{ comparison_field_values : "has many"
    comparison_fields ||--o{ comparison_field_values : "has many"
    apartment_types ||--o{ recommendation_requests : "receives recommendations"
    
    apartment_types {
        bigint id PK
        string name
        string slug
        decimal base_price_nightly
        int capacity_adults
        int capacity_children
        int bedrooms_count
        int bathrooms_count
        array amenities
    }
    
    comparison_fields {
        bigint id PK
        string field_key
        string label
        string type
        int order_index
    }

    comparison_field_values {
        bigint id PK
        bigint apartment_type_id FK
        bigint comparison_field_id FK
        string value
    }

    recommendation_requests {
        bigint id PK
        string purpose
        string guests_count
        string duration
        string budget
        array amenities
        bigint recommended_apartment_type_id FK
        string preferred_action
        string ip_address
    }
```

### Dynamic Migration Files
* `2026_05_31_150000_create_comparison_field_values_and_recommendation_requests_tables.php`: Declares relationships and logging tables ensuring clean referential integrity constraints.
* **DatabaseSeeder Integration:** Rerunnable seeder blocks establish 13 distinct comparison matrix rows, including Price, Bed Count, Kitchen access, Snooker/PS5, and Airport transits for all 4 luxury suites.

---

## 3. High-Fidelity User Experience (UX)

### Responsive Matrix Mechanics
* **Sticky Column Headers:** The desktop `<table>` incorporates `sticky top-[72px]` styling to keep the suite names and booking rates visible as the user scrolls.
* **Dynamic Row Compaction:** An Alpine.js toggle empowers users to hide/show identical fields. If a feature (e.g., "Air conditioning" or "Wi-Fi") is identical across all four apartments, the toggle gracefully hides the row to highlight distinct differentiators.
* **Mobile Adaptability:** On smaller viewports, the tabular columns transform automatically into stacked, highly readable apartment cards, maintaining the comparative bullet list with identical-row hiding logic.

### Interactive stay-persona Questionnaire Wizard
The questionnaire operates fully asynchronously (AJAX via Fetch API) inside a secure post route, saving logs to the database to support business intelligence analytics:
1. **Purpose:** Business, Leisure, Group, Corporate, Long stay, or Airport transit.
2. **Capacity & Duration:** Number of guests (`1`, `2`, `3-4`, `5+`) and duration of stay.
3. **Budget & Action:** Preferred pricing tier and notification format.
4. **Amenities:** Custom checkboxes.
5. **Dynamic Matching Algorithm:** Implements robust logical branching (e.g., solo executives are matched to 1-Bed Master Suites, larger teams are channeled into the 4-Bed Penthouse). Returns standard confirmation toasts and pre-populated WhatsApp redirection templates.

---

## 4. Branding and Style System Adherence

We have rigorously observed all styling rules defined in the Kevron guidelines:
* **Typography:** Premium headings strictly styled with `Marcellus` (caps size set to `1.8rem` for H1 and below `1.6rem` for H2). Body copy and UI labels strictly capped under `0.875rem` using standard `Inter`.
* **Pill-Rounded Actions:** All button elements carry `border-radius: 50px;` with active state scale transformations (`scale(0.96)`) and smooth transitions (`transition-all duration-400`).
* **Card Corner Metrics:** Custom cards and tables leverage strict `border-radius: 0.1rem;` sharp corners coupled with the harmonious container line-shadow (`box-shadow: rgba(0, 0, 0, 0.05) 0px 0px 0px 1px;`).
* **Luxurious Theme Coloring:** Palette draws entirely from Kevron Royal Blue (`#2B3192`), Sky Cyan (`#1FADEA`), Champagne Gold (`#D6A84F`), Midnight Navy (`#080D2B`), and Soft Ice Blue (`#F4F8FF`) with clear light/dark mode compatibility.

---

## 5. SEO and Generative AI Optimizations

* **Structured JSON-LD Breadcrumbs & ItemList:** Automatically injected at the head of the page to present a clean crawlable index of accommodation products.
* **Canonical URL Rendering:** Set cleanly via the application route request to prevent search-result duplicates.
* **Crawlable GEO Facts:** Includes an explicitly styled facts section summarizing Adeniyi Jones location coordinates, local branch details, and MMIA airport distances, allowing AI engines to parse details instantly.
* **SEO Metadata Fallbacks:** Incorporates dynamic database-driven titles, Open Graph (OG) cards, and descriptions mapped directly inside `seo_metadata` tables.

---

## 6. Automated Testing Actions

We added a complete, robust feature test in `tests/Feature/BookingFlowTest.php`:
* `test_compare_apartments_page_and_recommendation_flow`
This test clears apartment states, inserts mock matrix records, asserts page loads successfully with the correct `Marcellus` H1, checks dynamic currency strings, and validates the asynchronous stay-persona recommendation engine outcomes.
* **Execution:** All 28 automated tests (140 assertions) passed successfully with a build runtime of under 3 seconds!

---

## 7. Operational Guidelines for Administrators

* **To Add a Comparison Row:** Navigate to the Filament dashboard, add a new record inside the **Comparison Field Manager**, and assign values to each of the four suites in the **Comparison Field Value Manager**.
* **Reviewing Lead Enquiries:** Submissions from the questionnaire are logged in the **Recommendation Request Manager** with visitor IPs, preferred actions, and matched suites to enable lead follow-up.