# Apartments Listing Implementation Notes

This document summarizes the architecture, design choices, and implementation details of the **Apartments / Suites Listing Page** at `/apartments`.

---

## 1. Architectural Design

The Apartments Listing Page is built using a hybrid server-side and client-side approach to maximize performance, maintain SEO indexing capability, and deliver a smooth, SPA-like user experience.

- **Server-Side Render (Blade)**: On direct page loads (e.g. from Google Search or direct navigation), the page is rendered fully by Laravel. This ensures search engines can crawl all apartment descriptions, pricing rules, reviews, and dynamic FAQs.
- **Client-Side AJAX (Alpine.js & Fetch)**: Whenever a user interacts with search filters (dates, bedrooms, guests count, price bounds, or amenities), Alpine.js intercepts the change and fetches the filtered grid asynchronously.
- **Partial Renders**: The `ApartmentController` detects AJAX requests (via `XMLHttpRequest` or `ajax=1` query parameters) and returns only the card grid Blade fragment ([grid.blade.php](file:///c:/xampp/htdocs/kevronapartments/resources/views/apartments/partials/grid.blade.php)). Alpine.js swaps this HTML into the grid container, updating the browser history using `pushState` for shareable, bookmarkable search results.

---

## 2. Database Schema Details

We added the following tables to manage dynamic listing parameters and settings:
- **`media_assets`**: Stores absolute file paths for images and virtual previews, alt text, and primary indicators.
- **`apartment_type_media`**: Pivot table mapping assets to room categories with ordering indicators.
- **`seo_metadata`**: Polymorphic table mapping meta titles, descriptions, canonical URLs, and Open Graph tags to resources or pages.
- **`schema_metadata`**: Polymorphic table storing structured JSON-LD schemas (such as `FAQPage` or `ItemList` schemas).
- **`comparison_fields`**: Defines keys, labels, types, and positions for side-by-side comparison tables.
- **`apartment_types` (Modification)**: Added `best_for` string column to detail suitability labels (e.g. `'Solo Executives & Couples'`).

---

## 3. High-Fidelity UI Interactions

- **Sticky Filter Bar**: Pins to the top of the grid upon scroll, housing checks for check-in/out dates, capacity, room count, price range, and amenity tags.
- **Quick View Modal**: Renders on-card suite profiles, with image carousels, full specifications, and booking anchors. Fully keyboard-navigable with focus traps and Escape key dismissal.
- **Floating Compare Tray**: Appends to the bottom of the viewport when two or more checkboxes are checked. Allows side-by-side modal comparison of up to four suites.

---

## 4. SEO & Schema Mappings

- **Crawling Entities**: Embedded GEO entity description block outlining location proximities and airport travel times.
- **Breadcrumb & Listing Schema**: Injected dynamic `ItemList` JSON-LD schemas representing listing cards, and `FAQPage` schemas indexing selection queries.