# Cookie Policy & Consent Management System — Implementation Notes

This document provides a comprehensive overview of the design, architecture, database schemas, administration resources, dynamic frontend widgets, consent-aware script loader, and test suites built for the **Cookie Policy and Consent Management System** at Kevron Suites and Apartments.

---

## 1. Governance & Compliance Architecture
The consent system is built in strict alignment with the **Nigeria Data Protection Act (NDPA) 2023** and international privacy guidelines (GDPR/ePrivacy):
- **Zero Pre-Ticked/Opt-In Triggers:** Non-essential cookies (preferences, analytics, marketing) are strictly blocked from loading on initial visit.
- **Granular Consent Choice:** Guests can independently accept or decline specific tracking categories without impairing basic room booking capabilities.
- **Audit-Logged Consent Trial:** Every consent event (banner shown, accept all, customization saves) is securely logged with anonymous tokens, policy versions, IP hash hashes, and agent signatures.

---

## 2. Database Models & Schema Specifications

The system runs on the active InnoDB engine. Tables are fully migrated:

```mermaid
classDiagram
    CookiePolicy "1" --> "*" CookiePolicySection : hasMany
    CookieCategory "1" --> "*" CookieItem : hasMany
    CookieConsent "1" --> "*" CookieConsentPreference : hasMany
    CookieConsent "1" --> "*" CookieConsentEvent : hasMany
    
    class CookiePolicy {
        +int id
        +string title
        +string slug
        +string version
        +string status
        +date effective_date
        +datetime last_updated_at
    }
    
    class CookiePolicySection {
        +int id
        +int cookie_policy_id
        +string section_key
        +string heading
        +text body
        +int sort_order
        +boolean is_active
    }
    
    class CookieCategory {
        +int id
        +string name
        +string slug
        +text description
        +boolean consent_required
        +boolean always_active
    }
    
    class CookieItem {
        +int id
        +int cookie_category_id
        +string name
        +string provider
        +text purpose
        +string duration
        +string type
    }
    
    class CookieConsent {
        +int id
        +string anonymous_consent_id
        +string cookie_policy_version_id
        +string consent_context
        +string ip_address
        +text user_agent
    }
```

### Table Schemas:
1. **`cookie_policies`**: Tracks version headers, dates, and legal/management approval statuses (`draft`, `approved`, `published`).
2. **`cookie_policy_sections`**: Modular HTML legal clauses linked directly to active versions.
3. **`cookie_categories`**: Governance definitions (e.g. `necessary`, `preferences`, `analytics`, `marketing`, `functional`).
4. **`cookie_items`**: The dynamic active Cookie Register table directory listing token name, duration, purpose, type, and source.
5. **`cookie_consents`**: Anonymized consent session audit logs.
6. **`cookie_consent_preferences`**: Granular consent switches mapping users/tokens to categories.
7. **`cookie_consent_events`**: Audit trail timeline logging interaction actions (`accept_all`, `reject_non_essential`, `preferences_saved`).

---

## 3. Public Web Routing & Permanent Redirects
The routes are registered in `routes/web.php` supporting public-facing paths, redirects, and state updates:

- **GET `/cookie-policy`**: Calls `CookiePolicyController@index`. Fetches active published policy clauses, cookie categories, active register table items, related FAQs, dynamic SEO meta, and builds JSON-LD schemas.
- **POST `/cookie-policy/consent`**: Calls `CookiePolicyController@saveConsent`. Accepts AJAX requests securely validating preference checkbox parameters and writes audit events.
- **301 Permanent Redirects:** 
  - GET `/cookies` $\rightarrow$ `/cookie-policy`
  - GET `/policies/cookie-policy` $\rightarrow$ `/cookie-policy`

---

## 4. Frontend & User Interface Components

### 4.1 Global Premium Layout (`cookie_policy/show.blade.php`)
Crafted with Marcellus luxury headings (`Max 1.8rem`) and Inter body text (`0.875rem`) using HSL brand colors:
- **Scroll Spy Sidebar:** Floating Table of Contents tracking active scroll states. Includes real-time search filtering.
- **Alternating Sections:** Backgrounds alternate between Cloud White (`#FFFFFF`) and Soft Ice Blue (`#F4F8FF`) to ensure readability.
- **Accessible FAQs:** Interactive collapsible accordion built using Alpine.js and database FAQ records.
- **Dynamic Register Directory:** Elegant mobile-responsive tables grouping first-party and third-party tokens dynamically.

### 4.2 Interactive Cookie Banner (`layouts/app.blade.php`)
Positioned floating in the bottom viewport with HSL design parameters:
- **Action Buttons:** Standard `50px` rounded pills supporting "Accept All", "Reject Non-Essential", and "Manage Preferences".
- **Built-in Customize Drawer:** Expands directly within the banner, letting guests configure category choices without leaving the active page.
- **Cross-Component Events:** Toggling preference switches on the Cookie Policy index page immediately syncs checkboxes inside the banner widget.

---

## 5. Dynamic Consent-Aware Script Loader
To eliminate premature script injection, third-party analytics and marketing trackers are registered with plain text types:

```html
<script type="text/plain" data-consent-category="analytics">
    // Google Analytics (GA4) tracker script code...
</script>
<script type="text/plain" data-consent-category="marketing">
    // Meta / Facebook Pixel tracker script code...
</script>
```

### Injection Flow:
1. Browser loads layout and reads standard text scripts (which do NOT execute).
2. The consent manager loads choices from `localStorage` (`cookie-consented-categories`).
3. For each active/consented category, the manager replaces plain text script representations with executable `text/javascript` elements, loading trackers dynamically!
4. Updating consent immediately invokes the loader to run newly allowed scripts in real time without refreshing the viewport.

---

## 6. Verification and Automated Testing
We deployed a comprehensive feature testing suite in `tests/Feature/CookiePolicyTest.php` asserting:
1. **Public View Loads:** `/cookie-policy` loads and renders correct headings and sections.
2. **Permanent Redirections:** `/cookies` and `/policies/cookie-policy` return `301` status headers.
3. **Draft Shield Safety:** Moving the active policy status to `draft` immediately blocks public browsing with `404 Not Found`.
4. **AJAX Audit Save Logs:** Posting choice selections successfully updates the `cookie_consents`, `cookie_consent_preferences`, and `cookie_consent_events` tables.

*Test Verification status:* **100% PASS** (4 tests, 20 assertions).