Umbra-Bookshelf/BD-Murphy-Website-Specification-v2.0.md

# BDMurphy BookShelf Template - Technical Specification v2.0

**WordPress Theme:** BDMurphy BookShelf  
**Plugin 1:** BD-BookShelfHelper  
**Plugin 2:** BD-SimpleEmail  

**Version:** 2.0 | April 2026  
**Updated:** Incorporates WordPress Coding Standards, Security Best Practices, Accessibility Requirements, and Testing Standards

---

## Table of Contents

1. [Project Overview](#1-project-overview)
2. [Theme - Global Layout](#2-theme---global-layout)
3. [Theme - Pages](#3-theme---pages)
4. [Design System](#4-design-system)
5. [Plugin: BD-BookShelfHelper](#5-plugin-bd-bookshelfhelper)
6. [Plugin: BD-SimpleEmail](#6-plugin-bd-simpleemail)
7. [Database Schema](#7-database-schema)
8. [Design Decisions](#8-design-decisions)
9. [Implementation Standards](#9-implementation-standards)
10. [Quality Requirements](#10-quality-requirements)
11. [Deployment Checklist](#11-deployment-checklist)

---

## 1. Project Overview

### 1.1 Purpose

This specification defines a custom WordPress theme and two companion plugins for author B.D. Murphy's website. The system allows the author to showcase books, publish blogs, manage reviews, and send newsletters with minimal technical knowledge required after initial setup.

**Theme Name:** BDMurphy Bookshelf  
**Plugin 1:** BD-BookShelfHelper  
**Plugin 2:** BD-SimpleEmail  

### 1.2 Deliverables

- **WordPress Theme:** BDMurphy Bookshelf — custom theme, fully Customizer-driven
- **Plugin: BD BookShelfHelper:** Book data, series, pen names, short links, review links, SEO, and platform integrations. Book data stored and managed in one place accessable everywhere.
- **Plugin: BD SimpleEmail:** Subscriber management and AI-assisted newsletter delivery

### 1.3 Design Identity

| Element | Specification |
|---------|--------------|
| Logo | Quill-pen hybrid icon with "B.D. Murphy" in serif text file: "Icon_Quill_BDMurphy_Black_WhtBG.jpg" |
| Banner | 1200x200px illustrated timeline file: "Reading_History_banner_1200x200.jpg" |
| Primary Color | Navy blue (#1B3A6B) |
| Accent Color | Warm gold (#C8A96E) |
| Background | Parchment (#F5F0E8) |
| Heading Font | Playfair Display / Georgia fallback |
| Body Font | Lato / Calibri fallback |

### 1.4 General Behavior

All books and blog content displays in reverse chronological order by first-published date unless a manual sort position is assigned. Series content sorts by volume number within the series. UI chrome follows the site language setting; content stays in the language it was authored in.

### 1.5 WordPress Coding Standards Compliance

All code MUST comply with [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/):

- **PHP:** PSR-12 compatible with WordPress conventions
- **JavaScript:** ES5+ with JSHint validation
- **CSS:** WordPress CSS coding standards
- **HTML:** Semantic HTML5, no inline styles except where unavoidable
- **Text Domain:** `bd-murphy` for theme, `bd-bookshelfhelper` and `bd-simpleemail` for plugins

---

## 2. Theme - Global Layout

### 2.1 Header

- Banner image (1200x200px) via `add_theme_support('custom-header')`
- Default asset: `Reading_History_banner_1200x200.jpg`
- Site logo via `add_theme_support('custom-logo')`
- Default logo asset: 'Icon_Quill_BDMurphy_Black_WhtBG.jpg'
- Admin bar offset handled via `body.admin-bar` rules

### 2.2 Navigation Menu

- Registered via `register_nav_menus(['primary' => 'Primary Menu'])`
- Default items: Home, Blog, Books, Series (conditional), Reviews, About, Contact
- Sticky behavior with gold top border on scroll
- Series menu item conditionally rendered by BD BookHelper

### 2.3 Footer

- Three-zone layout: social icons, donate buttons, utility links
- Two widget areas: "Footer Left" and "Footer Right"
- Sign-up prompt with link to /signup/ page

### 2.4 WordPress Customizer Settings

| Setting | Function | Location |
|---------|----------|----------|
| Site title | `get_bloginfo('name')` | Settings > General |
| Logo | `the_custom_logo()` | Customizer > Site Identity |
| Banner | `get_header_image()` | Customizer > Header Image |
| Background | Custom background | Customizer > Background |
| Primary color | `get_theme_mod('primary_color', '#1B3A6B')` | Customizer > Colors |
| Accent color | `get_theme_mod('accent_color', '#C8A96E')` | Customizer > Colors |
| Fonts | `get_theme_mod('heading_font', ...)`, etc. | Customizer > Typography |

### 2.5 Theme Options Admin Screen

Settings saved via WordPress Settings API in `bdm_theme_options`:

- Social media URLs (X/Twitter, Facebook, LinkedIn, Instagram)
- Donation URLs (Buy Me a Coffee, PayPal)
- Author photo (media attachment ID)
- Sticky navigation toggle
- Posts per page
- Show read time toggle
- Business information (for CAN-SPAM compliance)

---

## 3. Theme - Pages

### 3.1 Home Page (front-page.php)
Top will be the banner using 100% of screen.
Line two will be the menu line. Each menu item as shown the menu setup.
Two-column layout: 66% content, 34% sidebar. Content via WordPress block editor. Sidebar contains book shelf widget with the default as custom HTML with the goodreads book list for bdmurphy.
The main page will have a short url from the plugin BookShelf Helper [all-books]

### 3.2 Blog Page (/blog/)

Template: `archive.php` or `home.php`. Lists posts with title, date, category, excerpt, featured image. Paginated (10 per page). Social sharing on individual posts.

### 3.3 All Books Page (/books/)

Template: `archive-book.php`. Stacked list with cover, title, author, ratings, format toggle, retailer buttons. Each book links to its detail page via short URL.

### 3.3.1 Shortcode Display

Books displayed via `[bd-book]` or `[bd-books]` shortcodes:
- Cover image (clickable, links to detail page)
- Title (clickable, links to detail page)
- Author/Pen name
- Blurb excerpt (HTML content, truncated)
- Retailer purchase buttons
- "View details" link to book detail page

### 3.4 Individual Book Page (single-book.php)

Full-width template with:
- Language selector tabs (EN, FR, DE, ES, RU, ZH-S, IT, PT, JA)
- Cover image (220x310px)
- Title, pen name, series info
- Ratings, format toggle, retailer links
- Read preview, pull quotes, reviews
- Share button (copies short URL)
- Social sharing buttons

**Short Link Access:** Books are accessible via short URLs using the slug defined in book metadata. URL pattern: `/{short-slug}` (e.g., `/ph/` for "Pandemic Hacker")

**Blurb HTML:** Descriptions are stored as HTML, allowing rich formatting (paragraphs, bold, italic, links) in book listings and detail pages.

### 3.4.1 My Books Submenu

The "My Books" menu item displays a dropdown submenu with links to each book's detail page:

```
My Books (top-level)
├── Book Title 1
├── Book Title 2
└── ...
```

- Each book appears as a submenu item
- Links point to the book's detail page using short URL
- Books sorted alphabetically by title
- Only published books shown

### 3.5 Reviews Page (/reviews/)

Template: `page-reviews.php`. Two-column grid with book cards and review summaries.

### 3.6 About Page (/about/)

Template: `page-about.php`. Two-column with author bio, awards, donate buttons, sign-up prompt.

### 3.7 Series Pages

- Listing: `archive-series.php` at /series/
- Individual: `taxonomy-series.php` or `single-series.php` at /series/{slug}/
- Series nav item hidden when no series exist

### 3.8 Sign-up Page (/signup/)

Template: `page-signup.php`. Email, first name, opt-in checkbox. Shortcode `[bdm_signup]` available.

### 3.9 Social Sharing Buttons

Platforms: Facebook, X/Twitter, LinkedIn, WhatsApp, Copy Link. Uses Web Share API where available. Book pages share the short URL.

### 3.10 Utility Pages

- Privacy Policy: standard WordPress page
- Unsubscribe: single email input + one-click HMAC tokens
- Contact: AJAX form with honeypot spam protection

---

## 4. Design System

### 4.1 Color Palette (CSS Custom Properties)

```css
:root {
    --bdm-navy: #1B3A6B;
    --bdm-slate: #2E6DA4;
    --bdm-sky: #4A90D9;
    --bdm-gold: #C8A96E;
    --bdm-cream: #F5F0E8;
    --bdm-parchment: #EDE4D0;
    --bdm-body-text: #2C2C2C;
    --bdm-mid-grey: #555555;
    --bdm-light-grey: #888888;
    --bdm-active-green: #2D6A4F;
}
```

### 4.2 Typography

- Headings: Playfair Display, Georgia, serif
- Body: Lato, Calibri, sans-serif
- Google Fonts loaded via `wp_enqueue_style()` with `display=swap`

### 4.3 Image Sizes

| Size | Dimensions | Use |
|------|-----------|-----|
| shelf-thumb | 44x62px (crop) | Book shelf widget |
| blog-thumb | 100x68px (crop) | Blog post thumbnails |
| rev-thumb | 52x74px (crop) | Review page covers |
| book-cover | 130x185px (crop) | All books page |
| book-page-cover | 220x310px (crop) | Individual book page |
| series-card | 400x280px (crop) | Series listing |
| series-header | 1200x300px (crop) | Series header |

### 4.4 Responsive Breakpoints

| Breakpoint | Layout |
|------------|--------|
| >=1200px | Full two-column, desktop nav |
| 768-1199px | Single column, hamburger menu |
| <768px | Single column, touch-friendly targets (44x44px min) |

---

## 5. Plugin: BD-BookShelfHelper

### 5.1 Overview

Manages all book-related data, series information, and pen name configuration. Registers "book" custom post type and "series" taxonomy.

### 5.2 Book Data Entry

**5.2.1 Data Entry Interface**

The plugin provides a dedicated book data entry page with the following UI requirements:

- **Input Fields:** Each data field has a dedicated input control (text, textarea, select, date picker as appropriate)
- **Labels:** Every field has a visible label using `<label>` elements properly associated via `for` attribute
- **Hints:** Helper text below each field provides context, format requirements, and examples
- **Validation:**
  - Real-time validation on blur with visual feedback (green checkmark for valid, red border + message for invalid)
  - Server-side validation on save with error messages displayed above problematic fields
  - Required fields marked with asterisk and validated before submission
  - Format validation: ISBN-13 (13 digits), ASIN (10 alphanumeric), dates (YYYY-MM-DD), URLs (valid format)
- **Organization:** Fields grouped into logical sections with collapsible headers:
  - Basic Information (title, pen name, publication date)
  - Identifiers (ISBN-13, ASIN)
  - Series & Order (series selection, volume number)
  - Content (blurb, preview excerpt, pull quotes)
  - Metadata (genre tags, Amazon search terms)
  - Retailer Links (Amazon, Apple, Google, B&N, Kobo)
  - Reviews (add/edit reviews)
- **Multi-language Tabs:** Language selector tabs for entering content in each supported language
- **Auto-save Draft:** Automatic saving of work in progress every 60 seconds
- **Preview:** Button to preview how the book will appear on the front-end

**Core Fields (language-independent):**
- Cover image (per language)
- Pen name (from configured list)
- Publication date, sort order
- ISBN-13, ASIN
- Series, volume number
- Short link slug

**Content Fields (per language):**
- Title, blurb, preview excerpt
- Pull quotes (up to 5)
- Genre tags (min 3)
- Amazon search terms

**Reviews (per book):**
- Comment text, source name, source URL
- AI-generated 3-line synopsis
- Display order

**Supported Languages:** EN, FR, ES, DE, IT, PT, RU, JA, ZH (Simplified)

### 5.3 Series Management

- Series name, slug, cover graphic, blurb, display order
- Book series assignment with volume number
- Conditional nav item rendering

### 5.4 Pen Name Management

- Up to 10 pen names
- Active/inactive toggle
- Notes field (internal only)
- Per-book assignment

### 5.5 Retailer Purchase Links

| Retailer | Formats | URL Pattern |
|----------|---------|-------------|
| Amazon | Ebook, Paperback, Hardback | `amazon.com/dp/{ASIN}?tag={affiliate_id}` |
| Apple Books | Ebook | URL with `at=` parameter |
| Google Play | Ebook | URL with partner code |
| Barnes & Noble | All | URL with affiliate parameter |
| Kobo | Ebook | URL with affiliate parameter |

### 5.6 Short Link System

**Book Short Links:**
- Auto-generated from first letter of significant words
- Examples: "Pandemic Hacker" → `/ph/`, "Deal Hunter" → `/dh/`
- Conflict check with incrementing numbers

**Review Short Links:**
- Pattern: `{book-slug}r{site-code}` (e.g., `dhrG` = Deal Hunter Goodreads)
- Lifecycle: Reserved → Pending → Active

### 5.7 Goodreads Integration

- Daily WP-Cron refresh
- Parses widget HTML for book data
- Author ID: 30469651

### 5.8 Amazon Ratings

- 6-hour WP-Cron scrape
- Staleness indicator on failure
- **Warning:** May conflict with Amazon Terms of Service

### 5.9 SEO Generation

Auto-generated on book save:
- Title tag, meta description
- Open Graph, Twitter Card tags
- schema.org Book structured data

### 5.10 Admin Menu Structure

```
BD BookHelper (top-level menu)
├── All Books
├── Add Book
├── Data Entry         (Enhanced interface per 5.2.1)
├── Series (taxonomy submenu)
├── Pen Names
├── Settings
│   ├── Affiliate Codes
│   ├── Goodreads
│   └── Amazon Scrape
└── Migrate            (Import from BD Books plugin)
```

### 5.11 Shortcodes

The plugin provides WordPress shortcodes for displaying book content:

| Shortcode | Description |
|-----------|-------------|
| `[bd-book book="1"]` | Display single book by ID or title |
| `[bd-books]` | Display all books in a list |

**Usage:**
```php
// Single book by ID
[bd-book book="42"]

// Single book by title
[bd-book book="Pandemic Hacker"]

// All books
[bd-books]

// Limit number of books
[bd-books limit="5"]
```

### 5.12 Migration from BD Books Plugin

The plugin includes a migration tool to import books from the original "BD Books" (bd-book-listing) plugin:

**Migration Process:**
1. Reads from `{$wpdb->prefix}bd_books` table
2. Creates new book CPT entries
3. Maps author to pen names (creates new if needed)
4. Imports descriptions as blurbs (English)
5. Imports cover images (WordPress media or external URLs)
6. Parses and maps purchase links to retailer fields

**Migrated Fields:**
| BD Books Field | BookHelper Target |
|---------------|------------------|
| title | Post title |
| author | Pen name (lookup or create) |
| description | blurb_{lang} meta |
| cover_image_id | Featured image (WordPress media) |
| cover_image_url | Downloaded and imported as attachment |
| purchase_links | Retailer URL metas (Amazon, Apple, B&N, Kobo, Google) |

**Admin Access:** BD BookHelper → Migrate

---

## 6. Plugin: BD-SimpleEmail

### 6.1 Overview

Handles email newsletter creation, subscriber management, and delivery via Gmail SMTP. AI-assisted composition via Gemini API.

### 6.2 Configuration

| Setting | Storage |
|---------|---------|
| Gmail address | `wp_options` |
| App password | Encrypted (openssl_encrypt) |
| Sender name | `wp_options` |
| Reply-to | `wp_options` |
| Gemini API key | Encrypted `wp_options` |

### 6.3 Email Composition Workflow

1. User opens "New Newsletter"
2. Enters subject and AI prompt (optional)
3. Plugin generates HTML via Gemini API
4. User edits draft
5. Optional: publish as blog post
6. Click "Send Newsletter" → sends to all subscribers via Gmail SMTP

### 6.4 Email Template

**Header:** Site name/logo  
**Body:** Composed content with affiliate links  
**Footer (mandatory):**
- Website URL
- One-click unsubscribe (HMAC-signed token)
- Full business address (CAN-SPAM)
- Unsubscribe text link

### 6.5 Subscriber Management

**Schema:**
```sql
bd_subscribers (
    id PRIMARY KEY AUTO_INCREMENT,
    email UNIQUE NOT NULL,
    first_name VARCHAR(100),
    status ENUM('subscribed', 'unsubscribed'),
    subscribed_at DATETIME,
    unsubscribed_at DATETIME NULL,
    ip_address VARCHAR(45),
    UNSUBSCRIBE_TOKEN VARCHAR(64) -- pre-generated
)
```

**One-Click Unsubscribe:**
- HMAC-signed token in every email
- Token format: `hash_hmac('sha256', email, AUTH_KEY)`
- Satisfies Gmail/Yahoo delivery requirements

### 6.6 Admin Menu Structure

```
BD SimpleEmail (top-level menu)
├── Subscribers
├── New Newsletter
└── Settings
    └── Gmail Configuration
    └── Gemini API
    └── About
```

---

## 7. Database Schema

### 7.1 BD BookHelper Tables

```sql
-- Core book record
CREATE TABLE {$wpdb->prefix}bd_books (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    post_id BIGINT NOT NULL,
    pen_name_id BIGINT,
    series_id BIGINT,
    volume_number INT,
    asin VARCHAR(20),
    isbn VARCHAR(20),
    publish_date DATE,
    sort_order INT DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY post_id (post_id)
);

-- Per-language content
CREATE TABLE {$wpdb->prefix}bd_book_meta (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    book_id BIGINT NOT NULL,
    language_code VARCHAR(5) NOT NULL,
    title VARCHAR(255),
    blurb TEXT,
    preview_excerpt TEXT,
    pull_quotes JSON,
    UNIQUE KEY book_language (book_id, language_code)
);

-- Series definitions
CREATE TABLE {$wpdb->prefix}bd_series (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    slug VARCHAR(100) NOT NULL UNIQUE,
    cover_attachment_id BIGINT,
    header_attachment_id BIGINT,
    blurb TEXT,
    display_order INT DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Pen names
CREATE TABLE {$wpdb->prefix}bd_pen_names (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    pen_name VARCHAR(255) NOT NULL,
    notes TEXT,
    active TINYINT(1) DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Reviews
CREATE TABLE {$wpdb->prefix}bd_reviews (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    book_id BIGINT NOT NULL,
    comment_text TEXT,
    synopsis TEXT,
    source_name VARCHAR(255) NOT NULL,
    source_url VARCHAR(500),
    display_order INT DEFAULT 0,
    KEY book_id (book_id)
);

-- Ratings cache
CREATE TABLE {$wpdb->prefix}bd_ratings (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    book_id BIGINT NOT NULL,
    source VARCHAR(20) NOT NULL,
    rating DECIMAL(3,2),
    review_count INT,
    last_updated DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY book_source (book_id, source)
);

-- Review short links
CREATE TABLE {$wpdb->prefix}bd_review_shortlinks (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    book_id BIGINT NOT NULL,
    site_code VARCHAR(5) NOT NULL,
    slug VARCHAR(20) NOT NULL UNIQUE,
    destination_url VARCHAR(500),
    status VARCHAR(20) DEFAULT 'pending',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    activated_at DATETIME
);
```

### 7.2 BD SimpleEmail Tables

```sql
-- Subscribers
CREATE TABLE {$wpdb->prefix}bd_subscribers (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    first_name VARCHAR(100),
    status VARCHAR(20) DEFAULT 'subscribed',
    subscribed_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    unsubscribed_at DATETIME,
    ip_address VARCHAR(45),
    unsubscribe_token VARCHAR(64)
);

-- Newsletter log
CREATE TABLE {$wpdb->prefix}bd_newsletters (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    subject VARCHAR(255) NOT NULL,
    body_html TEXT,
    sent_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    recipient_count INT DEFAULT 0
);
```

---

## 8. Design Decisions

| Decision | Answer | Rationale |
|----------|--------|----------|
| Child theme support | No | Customization via Customizer and Theme Options only |
| Dark mode | No | Light mode only, parchment palette |
| Sign-up form | Dedicated page (/signup/) | Shortcode `[bdm_signup]` also available |
| Visitor-submitted reviews | No | Admin-entered only |
| Social sharing | Yes | Web Share API with platform fallback |
| Series pages | Yes | Full series system with conditional nav |
| Affiliate codes | Optional | System works without, adds when available |
| One-click unsubscribe | Yes | HMAC-signed token per subscriber |

---

## 9. Implementation Standards

### 9.1 WordPress Architecture

1. **Custom Post Types:** "book" CPT registered by BD BookHelper (theme queries, doesn't register)
2. **Taxonomies:** "series" registered by BD BookHelper, attached to book CPT
3. **Rewrite Rules:** Short links via `add_rewrite_rule()`
4. **Internationalization:** Text domains (`bd-murphy`, `bd-bookshelfhelper`, `bd-simpleemail`), `load_theme_textdomain()` in functions.php
5. **Scheduled Tasks:** WP-Cron for Goodreads (daily), Amazon ratings (6 hours), review links (daily)
6. **Asset Loading:** All CSS/JS via `wp_enqueue_style()` and `wp_enqueue_script()` with handles, dependencies, version strings

### 9.2 Security Requirements

| Requirement | Implementation |
|-------------|----------------|
| Secrets storage | `openssl_encrypt()` with AES-256-CBC, key from AUTH_KEY |
| Unsubscribe tokens | `hash_hmac('sha256')` with AUTH_KEY |
| Output escaping | `esc_html()`, `esc_url()`, `esc_attr()`, `wp_kses_post()` |
| Input sanitization | `sanitize_text_field()`, `sanitize_email()`, `absint()`, etc. |
| CSRF protection | `wp_verify_nonce()` on all form submissions |
| Nonce verification | Nonce field + verification on every AJAX and form POST |
| Affiliate codes | Server-side application only, never in client-side code |
| Spam protection | Contact form honeypot field |

### 9.3 Required Theme Support Declarations

```php
add_theme_support('title-tag');
add_theme_support('custom-logo', array(
    'width' => 200,
    'height' => 200,
    'flex-width' => true,
    'flex-height' => true,
));
add_theme_support('custom-header', array(
    'default-image' => BDM_URI . '/assets/banner_1200x200_v3.png',
    'width' => 1200,
    'height' => 200,
    'flex-height' => false,
));
add_theme_support('custom-background', array(
    'default-color' => 'F5F0E8',
));
add_theme_support('post-thumbnails');
add_theme_support('html5', array(
    'search-form', 'comment-form', 'comment-list',
    'gallery', 'caption', 'script', 'style'
));
add_theme_support('automatic-feed-links');
add_theme_support('wp-block-styles');
add_editor_style('assets/editor-style.css');

add_image_size('shelf-thumb', 44, 62, true);
add_image_size('blog-thumb', 100, 68, true);
add_image_size('rev-thumb', 52, 74, true);
add_image_size('book-cover', 130, 185, true);
add_image_size('book-page-cover', 220, 310, true);
add_image_size('series-card', 400, 280, true);
add_image_size('series-header', 1200, 300, true);
```

### 9.4 Template File Structure

```
bd-murphy-author/
├── style.css              (Theme header: Name, Author, Version, Text Domain)
├── functions.php           (add_theme_support, register_nav_menus, etc.)
├── header.php             (wp_head, banner, nav, body_class())
├── footer.php              (Footer zones, wp_footer)
├── front-page.php         (Home page)
├── archive.php             (Blog posts)
├── archive-book.php        (All books)
├── single-book.php         (Individual book)
├── archive-series.php      (Series listing)
├── taxonomy-series.php     (Individual series)
├── page.php                (Default page)
├── page-full-width.php     (Template: Full Width)
├── page-no-sidebar.php     (Template: No Sidebar)
├── page-about.php         (Template: About)
├── page-reviews.php       (Template: Reviews)
├── page-signup.php        (Template: Sign Up)
├── page-unsubscribe.php   (Template: Unsubscribe)
├── page-contact.php       (Contact with AJAX)
├── 404.php
├── search.php
└── inc/
    ├── customizer.php
    ├── theme-options.php
    ├── template-tags.php
    ├── widgets.php
    └── nav-menu.php
```

### 9.5 Required Template Tag Usage

| Tag | Location | Purpose |
|-----|----------|---------|
| `body_class()` | `<body>` | Plugin hooks, admin bar offset |
| `post_class()` | Article wrappers | Plugin hooks, state classes |
| `wp_head()` | Before `</head>` | Plugin hooks, styles |
| `wp_footer()` | Before `</body>` | Plugin hooks, scripts |
| `the_custom_logo()` | Header | Logo output |
| `get_header_image()` | Header | Banner output |
| `wp_nav_menu()` | Header, Footer | Navigation menus |
| `dynamic_sidebar()` | Sidebar areas | Widget areas |
| `do_action('bdm_post_published', $post_id)` | On publish | Future plugin hook |

### 9.6 Hooks Reference

**Actions:**
- `bdm_post_published` — Fired on book/blog post publish (future plugin hook)

**Filters:**
- `bdm_nav_menu_items` — Filter for Series menu conditional
- `bdm_social_share_url` — Filter share URLs
- `bdm_email_footer_content` — Filter email footer

---

## 10. Quality Requirements

### 10.1 Testing Standards

**Unit Tests (Required):**
- All helper functions must have PHPUnit tests
- Minimum 80% code coverage for utility functions
- Test data factories for books, series, subscribers

**Integration Tests:**
- Plugin activation/deactivation
- Database table creation
- Custom post type registration
- REST API endpoints

**E2E Tests (Recommended):**
- Sign-up flow
- Unsubscribe flow
- Newsletter send flow
- Contact form submission

### 10.2 Accessibility Requirements (WCAG 2.1 AA)

| Requirement | Implementation |
|-------------|----------------|
| Keyboard navigation | All interactive elements focusable |
| Skip links | "Skip to content" link in header |
| ARIA labels | `aria-label`, `aria-expanded`, `role` attributes |
| Color contrast | Minimum 4.5:1 for text |
| Focus indicators | Visible focus styles |
| Screen reader | Semantic HTML, screen reader text |
| Touch targets | Minimum 44x44px on mobile |

### 10.3 Performance Targets

| Metric | Target |
|--------|--------|
| Page load | < 2 seconds |
| Time to first byte | < 600ms |
| Lighthouse Performance | > 90 |
| Lighthouse Accessibility | > 95 |

**Optimization Requirements:**
- Lazy loading for images (`loading="lazy"`)
- Minified CSS and JavaScript in production
- GZIP compression enabled
- Object caching enabled (Redis/Memcached recommended)
- Database query optimization with proper indexing

### 10.4 Security Audit Checklist

- [ ] All user input sanitized
- [ ] All output escaped
- [ ] Nonces verified on all form submissions
- [ ] Capabilities checked on admin actions
- [ ] SQL injection prevention (prepared statements)
- [ ] XSS prevention (escaping)
- [ ] CSRF protection (nonces)
- [ ] Stored secrets encrypted
- [ ] File upload validation
- [ ] Rate limiting on contact form
- [ ] Security headers (X-Content-Type-Options, X-Frame-Options, CSP)

---

## 11. Deployment Checklist

### 11.1 Pre-Deployment

- [ ] All code passes WordPress Coding Standards sniffs
- [ ] Unit tests pass with >80% coverage
- [ ] No debug output in production code
- [ ] Plugin uninstall.php created
- [ ] Plugin README.txt with installation instructions
- [ ] Theme screenshot.png (1200x900px)

### 11.2 Server Requirements

- [ ] WordPress 6.0+ installed
- [ ] PHP 7.4+ (8.2 recommended)
- [ ] MySQL 5.7+ or MariaDB 10.3+
- [ ] HTTPS enabled with valid certificate
- [ ] Memory limit >= 256M
- [ ] Max execution time >= 60s
- [ ] WP-Cron configured (DISABLE_WP_CRON = false)

### 11.3 Configuration

- [ ] AUTH_KEY, SECURE_AUTH_KEY, LOGGED_IN_KEY, NONCE_KEY defined
- [ ] `WP_DEBUG` disabled in production
- [ ] `WP_DEBUG_LOG` disabled in production
- [ ] `SAVEQUERIES` disabled in production
- [ ] Object cache (Redis/Memcached) configured
- [ ] CDN configured for static assets (optional)

### 11.4 Plugin Installation Order

1. Install and activate **BD-BookShelfHelper** first
2. Install and activate **BD-SimpleEmail** second
3. Upload and activate **BDMurphy Bookshelf** theme
4. Configure Theme Options (Appearance > Theme Options)
5. Configure BD BookHelper Settings
6. Configure BD SimpleEmail Settings

### 11.5 Post-Installation

- [ ] Permalinks flushed (Settings > Permalinks > Save)
- [ ] Sample data installed (if desired)
- [ ] Required pages created (/signup, /unsubscribe, /contact)
- [ ] Navigation menus configured
- [ ] Book shelf widget placed in Home Sidebar
- [ ] Test sign-up flow
- [ ] Test newsletter send
- [ ] Verify social sharing works
- [ ] Test mobile responsiveness
- [ ] Verify accessibility with screen reader

### 11.6 Ongoing Maintenance

- [ ] WordPress core updates tested before production deployment
- [ ] Plugin updates tested before production deployment
- [ ] Theme updates tested before production deployment
- [ ] Database backups before any update
- [ ] Security audit quarterly
- [ ] Performance audit bi-annually

---

## Appendix A: Disallowed Functions & Patterns

The following are NOT permitted in this project:

| Category | Disallowed |
|----------|------------|
| Database | `mysql_*` functions (use `$wpdb`) |
| Filesystem | `file_get_contents()` with URLs, direct file inclusion |
| Security | `eval()`, `exec()`, `shell_exec()`, `system()` |
| Output | `echo` without escaping, `print` without escaping |
| Deprecated | Any function marked deprecated in WordPress 6.0+ |

## Appendix B: Recommended Tools

- **Local Development:** Local by Flywheel, Docker, or VVV
- **Code Quality:** PHPStan, ESLint, Prettier
- **Testing:** PHPUnit, WP_Mock, Codeception
- **Security:** WPScan, Sucuri, Wordfence
- **Performance:** Query Monitor, New Relic, GTmetrix

## Appendix C: Sample Data

On plugin/theme activation, install sample data:

1. Pen name "B.D. Murphy" as active default
2. Book "Pandemic Hacker" with placeholder cover
3. Pre-reserved review short links: phrA, phrG, phrB, phrK, phrP, phrL
4. Pre-configured retailer links for sample book
5. Three sample blog posts
6. Goodreads Author ID: 30469651

"Clear sample data" button in Theme Options removes all sample content.

---

**End of Specification v2.0**

For page mockups, see: BD-Murphy-Page-Mockups-v1.2.docx