A2 SEO Plugin Showcase

Public-safe showcase for a private WordPress SEO AI workflow plugin with human review gates, WooCommerce product optimization boundaries, and controlled OpenAI integration patterns.

This repository is documentation and sanitized portfolio proof only. It is not a source mirror. Production code, credentials, prompts, API keys, request payloads, logs, customer data, and private business rules stay in the private source repository.

Review Summary

• Problem: AI-assisted SEO can create operational risk if generated content is applied directly to products, posts, metadata, or schema.
• Solution: a modular WordPress workflow where generation, QA, human review, approval, apply, logging, and rollback are separate steps.
• Engineering focus: capability-gated admin actions, review-state transitions, structured provider responses, retry/budget controls, idempotency, and rollback safety.
• Public scope: architecture, workflow decisions, privacy boundary, and future sanitized snippets.

Business Context

WooCommerce catalogs need ongoing SEO updates: product descriptions, meta titles, meta descriptions, focus keywords, FAQs, internal links, source notes, and media support. AI can accelerate this work, but publishing generated content without review can damage brand tone, product accuracy, search quality, and customer trust.

The private plugin is designed around a safer operating model:

1. Collect product/context data from WordPress and WooCommerce.
2. Prepare structured AI requests through a provider boundary.
3. Validate generated output against expected fields and quality rules.
4. Store proposals as review items instead of applying them immediately.
5. Let authorized reviewers approve, request changes, reject, apply, or roll back.
6. Track jobs, logs, attempts, cost estimates, and scheduling decisions.

What This Demonstrates

• Human-reviewed AI-assisted SEO workflows for WooCommerce content.
• Separation between generation, QA, review, approval, apply, rollback, logging, and scheduling.
• WordPress capability design for settings, reviews, logs, and job execution.
• Provider boundary design for OpenAI-style structured responses, retries, rate limits, budgets, and model checks.
• Review-state and idempotency thinking through fingerprints and job locks.
• PHPUnit-backed workflow coverage for activation, review/apply/rollback, idempotency, scheduling, and locking.

Architecture Overview

The private implementation is modular rather than a single monolithic admin action:

• Plugin bootstrap: installs database structures, roles, capabilities, settings defaults, and modules.
• Settings layer: centralizes module toggles, provider settings, budgets, prompt versions, quality rules, scheduling, and publishing policy.
• Provider client: wraps structured AI requests, response parsing, retry behavior, budget checks, rate limits, and logging.
• Content generator: prepares product/article requests, computes input hashes/fingerprints, validates structured output, and normalizes fallback fields.
• SEO analyzer: evaluates generated content against configurable quality rules before it reaches review.
• Human review module: stores proposed changes as private review items with status transitions and review metadata.
• Apply/rollback module: applies only approved reviews and keeps original snapshots for rollback.
• Scheduler: queues product/article jobs through Action Scheduler when available, with WP-Cron fallback.
• Logging/database layer: records jobs, outputs, failures, retry context, and cost estimates without exposing secrets in public docs.

See docs/architecture-notes.md for the detailed reviewer walkthrough.

Key Engineering Decisions

• Human review is mandatory: generation does not equal publishing; content is staged as a review item first.
• Apply is status-gated: apply actions only proceed from approved review state.
• Rollback is part of the model: original post/content/meta snapshots are captured before applying changes.
• Provider logic is isolated: OpenAI-style API handling is behind a client boundary with structured output validation and retry handling.
• Budget and rate controls matter: AI workflows need cost and throughput guardrails, not just prompt execution.
• Public showcase excludes prompts: exact prompts, payloads, response contracts, and provider configuration are private.

Tech Stack

• WordPress plugin architecture
• WooCommerce product workflows
• PHP
• OpenAI integration boundary
• Admin review and queue concepts
• Action Scheduler / WP-Cron fallback
• Rank Math metadata integration boundaries
• PHPUnit workflow tests

Privacy Boundary

Public files describe architecture and engineering approach only. Production source, prompts, API keys, encrypted settings, request/response payloads, logs, product data, customer data, exact database schema, and private SEO strategy remain private.

Read the full boundary in docs/privacy-boundary.md.

Reviewer Path

• Start with this README for the business case and implementation shape.
• Read docs/architecture-notes.md for module responsibilities and workflow flow.
• Read docs/privacy-boundary.md for what is intentionally excluded.
• Check docs/update-notes.md for public-facing change history.
• Review samples/README.md for the Phase 3 sanitized sample plan.

Repository Structure

• docs/architecture-notes.md — architecture, workflow, and engineering decisions.
• docs/privacy-boundary.md — what is public versus private.
• docs/update-notes.md — public update log.
• samples/README.md — sanitized sample-code overview.
• samples/php/ — short public-safe PHP snippets for review states, structured response checks, and rollback snapshots.

Phase Status

• Phase 1: showcase skeleton, privacy boundary, and reviewer path.
• Phase 2: employer-friendly business context, architecture notes, and risk boundaries.
• Phase 3: sanitized snippets for review states, structured response checks, and rollback snapshots.

Links

• Portfolio: https://amiraliyaghouti.com
• GitHub profile: https://github.com/shiny-a2
• Private source: shiny-a2/a2-seo-plugin (not public)