# Guest Services Page — Technical Implementation Notes

## Project: Kevron Suites and Apartments
## URL: `/guest-services`
## Database Migrations: `2026_05_31_220000_create_guest_services_tables.php`
## Seeder: `GuestServiceSeeder.php`
## Test Suite: `tests/Feature/GuestServicesPageTest.php`

---

## 1. System Architecture

The Guest Services ecosystem is fully database-driven, integrating automated stays, keyless lock allocations, and concierge desks seamlessly.

```mermaid
graph TD
    A[Guest Visits /guest-services] --> B[Index Controller Loader]
    B --> C[Active Services Grid]
    B --> D[Public Manual Guides]
    B --> E[Dynamic FAQ Category]

    A --> F[Alpine.js Central Request Hub]
    F --> G[Dynamic Forms]
    G --> H[Turnstile & Rate Limited Endpoints]
    H --> I[Database Transactions]
    I --> J[Filament Admin Dashboards]
    I --> K[Queued Booking Notifications]

    A --> L[Verified Booking Reference Gate]
    L --> M[AJAX Manual Unlock API]
    M --> N[Protected SSID & Smart Lock Master Codes]
```

---

## 2. Brand Compliance & UI Styling Rules

The page strictly respects the luxury specifications of Kevron Suites and Apartments.

### A. Typography Constraints
* **Luxury Headings**: Marcellus (`font-family: 'Marcellus', serif;` clamped to a maximum size of `1.8rem`).
* **Body Texts & UI Labels**: Inter (`font-family: 'Inter', sans-serif;` with a maximum size capped at `0.875rem`).
* **Fonts Overrides**: Playfair Display is strictly prohibited.

### B. Element Architecture
* **Buttons**: Exactly `border-radius: 50px;` (pill style) with progressive champagne gold borders, hover transitions, and accessible `44px` minimum mobile touch targets.
* **Cards & Forms**: Exactly `border-radius: 0.1rem;` (premium square styling) and `box-shadow: rgba(0, 0, 0, 0.05) 0px 0px 0px 1px;`.
* **Deepening Effects**: Service cards and tabs use slow transition hover background modifications (`transition-colors duration-300`).

---

## 3. Database Table Definitions

Seeded via `GuestServiceSeeder` to avoid duplicates on reruns, storing distinct stays, check-ins, cleanings, and reviews.

* `guest_services`: Slug-mapped services list managing titles, descriptions, icons, form configurations, and display order.
* `digital_checkins`: Secure pre-arrival registrations storing occupant counts, booking references, and private credentials.
* `arrival_time_submissions`: Check-in prep times matched to arrival hours and travel modes.
* `special_requests`: Custom celebration or remote-office setups (birthdays, anniversaries, business support).
* `housekeeping_requests`: Linen refills, sweeps, and waste removals mapped to units.
* `maintenance_tickets`: Technical faults reported to on-site technicians with priority status histories.
* `reviews`: Post-stay feedback. Moderated by Filament admins before public publishing.
* `repeat_stay_requests`: Return guest loyalty deals and previous booking checks.
* `guest_manual_sections`: Categorized Wi-Fi network credentials, appliances guides, smart lock instructions, and emergency guidelines.

---

## 4. Privacy & Gated Access Controls

### Secure ID Uploads
* Guest identity uploads are strictly kept non-public.
* Files are uploaded securely and stored in `storage/app/secure/guest-ids`.
* Accessible ONLY to authenticated administrators in Filament via a custom controller mapping:
  `Route::get('/admin/guest-ids/{filename}', [GuestIdController::class, 'download'])`

### Booking Verification Manual Locks
* Sensitive manual parameters (SSIDs, Wi-Fi password `StayKevronGold2026`, and keyless deadbolt master codes) are redacted in public previews.
* Gated behind a secure form requiring a verified active booking reference (`KEV-XXXXX` codes matched dynamically).
* Authenticated bookings retrieve private unredacted `guest_manual_sections` via an AJAX POST dispatch:
  `Route::post('/guest-services/manual/unlock', [GuestServiceController::class, 'unlockGuestManual'])`

---

## 5. Notification Triggers

Whenever a form is successfully stored, a `BookingNotification` model is inserted to orchestrate notifications across Channels:

* **Email Templates**: Concierge receipts and early en-suite check-in updates.
* **SMS Triggers**: Immediate alerts for scheduled arrival transit bookings.
* **WhatsApp Messages**: Prefilled messages linking guests to support desks.

---

## 6. Automated Testing Suite

Comprehensive testing is implemented in [GuestServicesPageTest.php](file:///c:/xampp/htdocs/kevronapartments/tests/Feature/GuestServicesPageTest.php) verifying:
1. HTTP Index status 200 route loads.
2. Global header/footer presence (`KEVRON`, `Regina Coker Street`).
3. Marcellus & Inter size cap compliancy.
4. Input validation and database storage for all 9 forms.
5. Secure Upload and private disk storage for check-in documents.
6. AJAX booking ref verification and Wi-Fi credential unlock checks.
7. Event logging telemetry tracking.