# Kevron Suites and Apartments — Blog & City Guide System Implementation Notes

This document provides a comprehensive overview of the design, database schema, Filament administration features, public controller endpoints, interactive components, and search tracking of the **Blog and Ikeja City Guide System** at `/blog`.

---

## 1. Architectural Overview

The Blog & City Guide serves as a high-performance local SEO, transit guide, and corporate B2B direct-booking acquisition funnel. It is built to support search indexes, category listings, tag indices, detailed article structures, sticky Table of Contents panels, inline booking widgets, and post-specific FAQs.

```mermaid
graph TD
    A[Public Browser] -->|HTTP GET /blog| B[BlogController]
    B -->|Search/Filter/Sort| C[BlogPost Model]
    C -->|BelongsTo| D[BlogCategory]
    C -->|BelongsToMany| E[BlogTag]
    C -->|BelongsTo| F[BlogAuthor]
    C -->|HasMany| G[BlogPostFaq]
    C -->|MorphOne| H[SeoMetadata]
    C -->|MorphMany| I[SchemaMetadata]
    B -->|Render Blade| J[resources/views/blog/index.blade.php]
    B -->|AJAX render| K[resources/views/blog/partials/list_grid.blade.php]
```

---

## 2. Database Schema Adjustments

The system introduces a new migration `2026_06_01_170000_create_blog_system_additions.php` which creates 9 new tables and appends columns to the existing `blog_posts` table:

*   **`blog_authors`**: Holds editorial writer profiles, Roles (e.g. Guest Services), and bio paragraphs.
*   **`blog_tags`**: Stores tag badges (e.g. Lagos Airport, MM1, MM2, Corporate Stays).
*   **`blog_post_tag`**: Pivot table managing post-to-tag many-to-many pivots.
*   **`blog_posts` (Expanded)**: Adds `status` (draft → published), `is_featured`, `is_recommended`, `reading_time_minutes`, `robots`, `canonical_url`, and custom `blog_author_id`.
*   **`blog_post_faqs`**: Mapped 3–6 accordions visible to search engine spiders for `FAQPage` rich results.
*   **`blog_post_revisions`**: Keeps full-text content revisions to provide an editorial audit trail.
*   **`blog_post_redirects`**: Automatically captures old slugs when a post is modified and redirects permanently with a 301 status.
*   **`blog_events`**: Tracks user interactions: Page views, search terms, category filters, TOC scrolls, and CTA clicks.
*   **`blog_search_logs`**: Logs searches to identify content gaps.
*   **`blog_related_posts`**: Handles manual related article mapping.

---

## 3. Idempotent Data Seeding

The seeder `BlogDatabaseSeeder` populates the base structure:
1.  **8 Categories**: Ikeja Travel Guide, Airport Stay Guide, Business Travel, Family Stay, Luxury Staycation, Corporate Accommodation, Local Attractions, Safety and Comfort.
2.  **12 Default Tags**: Ikeja, Adeniyi Jones, Lagos Airport, MM1, MM2, etc.
3.  **Editorial Author**: Kevron Suites and Apartments Editorial Team.
4.  **12 Comprehensive Starter Articles**: Seeds full detailed local guides (MM1 proximity, Adeniyi Jones access, B2B billing cycles, weekly/monthly rates, safety Smart locks, car rentals) with individual post SEO tags, FAQ lists, and related posts.

---

## 4. Filament Administration Portal

Admin managers are set up in Filament:
*   **BlogPostResource**: Complete form layout featuring Content parameters, visibility statuses, reading times, SEO titles, robots tags, and an inline FAQ repeater. Tables display badge status and instant feature switches.
*   **BlogCategoryResource**: Directory folder management.
*   **BlogTagResource**: Tag catalog.
*   **BlogAuthorResource**: Editorial team profile control.
*   **BlogPostRedirectResource**: 301 audit redirects manager.
*   **BlogEventResource**: Analytic events viewer.

---

## 5. Front-end Views & Interactions

*   **`/blog` (Index)**:
    *   Marcellus and Inter typography caps enforced (H1 maximum `1.8rem`, other headings under `1.625rem`, body `0.875rem`).
    *   Pill buttons (`border-radius: 50px`) with slow bouncing 3D effects.
    *   Cards (`border-radius: 0.1rem`) with subtle shadows (`box-shadow: rgba(0,0,0,0.05) 0px 0px 0px 1px`).
    *   Real-time search form and quick category pills sending AJAX requests to retrieve the partial `blog.partials.list_grid`.
    *   Midnight navy booking block listing rates (₦150k to ₦300k).
*   **`/blog/{slug}` (Details)**:
    *   Immersive two-column layout.
    *   Dynamic client-side Table of Contents (TOC) builder extracting H2 titles, supporting smooth scroll and reduced motion.
    *   Prose pull-quotes and inline accommodation recommendation boxes.
    *   Keyboard accessible FAQ accordions utilizing semantic `<button>` selectors, `aria-expanded` and `aria-controls`.
    *   Author bio card, related article grids, and WhatsApp CTAs.

---

## 6. Telemetry & Analytics

Interactive events are recorded asynchronously via `POST /blog/track`:
*   `blog_index_viewed`
*   `blog_post_viewed`
*   `search_used` (logs queries to audit gaps)
*   `category_pill_clicked`
*   `toc_clicked` (tracks popular headings)
*   `faq_expanded`
*   `cta_clicked` (logs booking interest)

---

## 7. Quality Assurance and Feature Tests

Automated testing is located in `tests/Feature/BlogSystemTest.php`, confirming:
*   Main directory returns 200 OK and renders the proper H1.
*   Draft posts are strictly excluded from all public searches and direct accesses.
*   Real-time query filters produce accurate subset grids.
*   Category and Tag filters load properly.
*   Modifying an active post slug automatically saves a redirect rule and triggers a permanent 301 redirection.
*   JSON-LD Article schemas compile correctly.