# FAQ Knowledge Base Page — Technical Implementation Notes

This document describes the technical layout, database schema, Filament admin resources, AJAX search logic, and accessibility rules implemented for the new **Frequently Asked Questions (FAQ) Page** at `/faqs`.

---

## 1. Database Architecture & Migrations

We extended the basic FAQ structure to support dynamic categorization, metrics logs, and unanswered customer support pipelines:

### 1.1 `faq_categories`
- `description` (text, null): Describes each category context.
- `sort_order` (integer, default 0): Dictates display order on navigation pills and main grid.
- `is_active` (boolean, default true): Toggle categories globally.

### 1.2 `faqs`
- `slug` (string, index): Clean URL mappings for individual entries.
- `summary` (text, null): Shorter summary for search preview cards.
- `is_featured` / `is_popular` (boolean, default false): Tags initial popular list displayed in grid.
- `sort_order` (integer, default 0): Sorting priority within a category.
- `visibility` (string, default 'public'): public, confirmed_guests_only, admin_only.
- `last_reviewed_at` (timestamp, null): Date for administrative freshness tracking.

### 1.3 `faq_links`
- Mapped external/internal page references (e.g. `/booking`, `/guest-services`) to individual FAQs for structural linking.

### 1.4 `faq_feedback`
- Logs helpful and unhelpful guest votes (`is_helpful` boolean) coupled with optional commentary, allowing administrators to audit low-helpfulness articles.

### 1.5 `faq_search_logs`
- Traces search query parameters, client IP address, and results counts to help management find knowledge gaps.

### 1.6 `faq_unanswered_questions`
- Pipes unrouted questions directly to the support relations dashboard when searches return no matches.

---

## 2. Filament Admin Dashboard

We registered new resources inside the Filament panel for complete administrative control:
- **FAQ Manager**: Updates to `FAQResource` to cover slugs, featured, popular, and review datetime hooks.
- **FaqCategoryResource**: Active toggle, sort order, and descriptions.
- **FaqFeedbackResource**: Read-only listing of helpful/not-helpful logs and guest reviews.
- **FaqSearchLogResource**: Auditing of guest queries.
- **FaqUnansweredQuestionResource**: Resolving pending customer questions.

---

## 3. AJAX Live Search with Highlighting

- AJAX searches query active, public FAQs securely via `FaqController@search`.
- Standard case-insensitive SQL matching is applied to question and answer columns.
- Query terms are securely highlighted using high-performance PHP string replacements wrapped in `<mark>` tag styles.
- Logs search terms automatically subject to cookie/privacy consent.

---

## 4. Design Aesthetics & Visual Tokens

The frontend view `faqs/index.blade.php` is custom-tailored to respect Kevron Suites branding rules strictly:
- **Typography font limits**: Headings use `Marcellus` (H1 capped at `1.8rem`, H2-H6 capped at `1.5rem`), body and UI copy uses `Inter` (capped at `0.875rem`).
- **Button pills**: All CTA buttons use `border-radius: 50px` with 3D bouncy hover and slow transitions.
- **Cards/Components**: Border-radius is set to `0.1rem` with offset box-shadows, deepening backgrounds on hover.
- **Color harmony**: Utilizes Kevron Royal Blue (`#2B3192`), Sky Cyan (`#1FADEA`), Midnight Navy (`#080D2B`), and Champagne Gold (`#D6A84F`).
- **Reduced motion**: Built-in media query overrides to suppress transitions and translations for guests with motion sensitivities.
- **SEO/GEO Content**: Rich entity paragraphs highlighting Ikeja, Adeniyi Jones, and Murtala Muhammed International Airport landmarks to support generative AI search crawlers.
- **JSON-LD Schema**: Implements structured `FAQPage` schema to support organic crawlability.

---

## 5. Verification

- Feature tests in `tests/Feature/FaqsPageTest.php` cover:
  - Route resolving and response code status.
  - Presence of all 12 required categories.
  - Featured popular questions render.
  - Live AJAX search term matching and highlighting.
  - Zero-result search term logs.
  - Helpfulness feedback and comments storage.
  - Unanswered question submissions.
  - SEO and JSON-LD schema assertions.