Rivian Tire Guide

A comprehensive WordPress plugin that provides an interactive tire catalog for Rivian vehicle owners. Features advanced filtering, side-by-side comparison, user and guest reviews, affiliate link management, analytics, and an efficiency scoring system to help drivers choose the best tires for range and performance.

Features

Tire Catalog

• Vehicle Filter — Segmented toggle (All / R1 / R2) filters tires by Rivian vehicle. Vehicle-to-size compatibility is derived automatically from the stock wheels database — adding a wheel for a new vehicle makes it appear in the toggle with no extra configuration.
• Interactive Tire Cards — Browse tires with real-time filtering by size, brand, category, price, weight, warranty, 3PMS, EV rated, and studded availability.
• Smart Search — Fuzzy search with type-ahead suggestions for brands, models, categories, and sizes.
• Side-by-Side Comparison — Select up to 4 tires and compare specs on a dedicated comparison page with best-value highlighting.
• Shareable Filtered Views — All filter state persists in URL parameters (?brand=Michelin&size=275/65R18), enabling shareable links and browser back/forward navigation.
• Shareable Tire Links — Direct links to individual tires with deep-link highlighting.
• Active Filter Chips — Dismissible chips show active filters at a glance.
• Smart No Results — When filters produce no matches, actionable suggestions help users relax specific filters.
• AI Tire Advisor — "Help me choose" asks three questions and returns three picks with reasons and trade-offs, grounded in the catalog (only tires that fit the vehicle, only numbers from the guide). "What owners say" summarizes a tire's reviews on its page; the compare page opens with a plain-words paragraph. Runs on Claude through the Anthropic API; without a key, Help me choose falls back to the guide's own ranking rules.
• Changelog — A "Changelog" pill in the filter header opens plain-language release notes (from WHATS-NEW.md), with a dot until the newest release has been seen; the same notes live at /tire-guide/whats-new/.

Ratings & Reviews

• Star Ratings — SVG star ratings with half-star precision. Logged-in users rate tires 1-5 stars with keyboard navigation (arrow keys, Enter/Space). Users can delete their own ratings.
• Text Reviews — Optional review title and body alongside star ratings, with a slide-in reviews drawer for each tire.
• Guest Reviews — Non-logged-in visitors can submit reviews with name and email. Includes honeypot spam prevention and IP-based rate limiting.
• Review Moderation — Admin approval queue with pending/approved/rejected status tabs. Admin-submitted reviews auto-approve; user and guest reviews default to pending.
• Email Notifications — Admins receive styled HTML email notifications for new guest reviews. Reviewers receive approval notification emails.

Efficiency Scoring

• Proprietary Algorithm — Weighted formula (0-100 score, A/B/C/D/F grade) estimating range-friendliness based on weight, tread depth, load range, speed rating, UTQG, category, width, and 3PMS certification.
• Single Source of Truth — Calculation lives in RTG_Database::calculate_efficiency(). Admin form uses AJAX to call the PHP formula directly.

Real-World Efficiency (Rivian Roamer)

• Live Data Sync — Integrates real-world mi/kWh efficiency data from Rivian Roamer, collected from actual Rivian owner driving sessions. Syncs automatically every 5 minutes via WP-Cron.
• Admin Mapping — Auto-matches tires by brand + model + size. Ambiguous matches (same tire, different load ratings) are flagged for manual review on the Roamer Sync admin page. Multiple Roamer entries can be assigned to one tire with weighted-average efficiency.
• Tire Cards — Blue mi/kWh pill badge displayed alongside the calculated efficiency badge, with its own info tooltip linking to Rivian Roamer.
• Sort & Compare — "Real-World Efficiency" sort option and comparison row in Performance section.
• Dashboard — Roamer overview card (coverage, avg/best/worst mi/kWh, sessions, vehicles, last sync) and top 5 most efficient tires by real-world data.

Tire Discovery (Affiliate Catalog Monitoring)

• Daily Catalog Check — Watches affiliate catalogs for tires in Rivian fitments that aren't in the guide yet, so new arrivals surface on their own instead of waiting on a manual search of each size.
• Qualification Rules — Every product is judged against the guide's requirements: size must be a Rivian fitment, load index must clear a configurable floor (default 112 — the R2 minimum; R1 needs 116), and the listing must be identifiable. Specs are parsed out of the product title when the feed doesn't supply them as fields.
• Review Queue — Admin page badged with the number awaiting a decision, split across Awaiting Review / Near Misses / Already in Guide / Dismissed / Added and filterable by size. Near misses show the reason they were held back rather than being silently filtered out.
• One-Click Add — Opens the Add New Tire form prefilled with brand, model, size, price, load index, load range, speed rating and purchase link, plus derived diameter and max load.
• Sticky Dismissals — A dismissed candidate never returns to the queue, so it stays short enough to stay useful. Decisions made by a person always outrank what a later run concludes.
• Email Digest — Sent only when a run finds a qualifying tire not seen before.
• CJ Affiliate Integration — Both Tire Rack and SimpleTire run on CJ, so one connection covers both. Sends one shoppingProducts request per tire size, scoped to the configured advertisers. Includes a Test Connection button that runs a real query and reports CJ's own errors.
• Credential Handling — The CJ token is read from an RTG_CJ_PAT constant in wp-config.php when defined (keeping it out of the database), otherwise from a write-only settings field that never renders the saved value back. No credentials are stored in the repository.
• Pluggable Sources — Retailers sit behind the RTG_Catalog_Source interface and register via the rtg_catalog_sources filter. A JSON-backed source also ships with the plugin as a fallback for retailers with no machine-readable feed.

Analytics

• Click Tracking — Tracks affiliate link clicks (purchase, review) via navigator.sendBeacon() with 5-second server-side deduplication.
• Search Analytics — Tracks search queries, active filters, sort options, and result counts with client-side debounce and server-side deduplication.
• Admin Dashboard — Period selector (7/30/90 days), summary cards, Chart.js line charts for clicks and search volume, ranked tables for most clicked tires, top queries, zero-result searches, and most used filters.
• Data Retention — Configurable retention period (7-365 days) with daily WP-Cron cleanup.

Admin

• Dashboard — Overview cards (total tires, average price, efficiency, ratings), breakdowns by category/brand/size/grade, Rivian Roamer real-world efficiency overview and top 5 rankings, content health indicators (pending reviews, missing images/links). A quick-stats dashboard widget (with Roamer coverage) also appears on the main WordPress dashboard.
• Tire Management — Full CRUD with search, filters, bulk actions, tire duplication, and tag suggestions.
• CSV Import/Export — Bulk import with duplicate handling (skip/update), auto-generated IDs, auto-calculated efficiency, MIME validation, and full catalog export.
• Reviews Management — Pending/approved/rejected tabs with approve, reject, and delete actions.
• Affiliate Links Dashboard — Centralized view of all purchase and review links with link classification (affiliate vs. direct), filter tabs, and inline AJAX editing.
• Tire Discovery — Review queue for tires found in affiliate catalogs (see Tire Discovery section above), with its own settings for the daily check, the digest email, and the minimum load index.
• Stock Wheels Guide — Manage stock wheel data for Rivian models.
• Analytics — Visual analytics with Chart.js (see Analytics section above).
• Settings — Rows per page, compare slug, user reviews slug, server-side pagination toggle, theme colors (14 CSS custom properties), dropdown options (brands, sizes, categories, load ranges, speed ratings, size-to-diameter mapping, load index-to-lbs mapping), affiliate domains, and analytics retention.

SEO & Social

• Schema.org Structured Data — Automatic JSON-LD output (Product, AggregateRating, Review, ItemList) for rich search results.
• Open Graph & Twitter Cards — Sharing a ?tire= link shows rich previews with tire name, description, price, and image.

Performance

• Server-Side Pagination — Optional AJAX mode with server-side filtering/sorting for large catalogs (200+ tires). Client-side mode available for smaller catalogs.
• Transient Caching — Tire query results cached for 1 hour, automatically invalidated on write operations.
• Lazy Loading — IntersectionObserver-based image lazy loading with shimmer placeholders and 600px root margin preloading.
• Skeleton Loading — Shimmer placeholder cards display immediately while data loads.
• Minified Assets — esbuild produces .min.js and .min.css files with console stripping. Served automatically when SCRIPT_DEBUG is off.
• Inline SVG Icons — Replaced Font Awesome CDN (~60 KB) with lightweight inline SVGs for the ~35 icons used.

Accessibility

• Keyboard Navigation — Arrow keys, Enter/Space for star ratings. Tab navigation for all interactive elements.
• ARIA Attributes — role, aria-label, aria-checked, aria-expanded, aria-controls, aria-live on all interactive elements.
• Skip-to-Content Link — Keyboard shortcut to skip navigation.
• Focus-Visible Styles — Outline styles on all interactive elements.
• Screen Reader Support — .screen-reader-text utility class, status regions for dynamic content.
• Reduced Motion — Respects prefers-reduced-motion for animations.

REST API

• GET /wp-json/rtg/v1/tires — Filtered, paginated tire listing.
• GET /wp-json/rtg/v1/tires/{tire_id} — Single tire with ratings.
• GET /wp-json/rtg/v1/tires/{tire_id}/reviews — Paginated reviews.
• POST /wp-json/rtg/v1/efficiency — Calculate efficiency score from specs.
• GET /wp-json/rtg/v1/feed — Full tire catalog JSON feed with ratings and Roamer real-world efficiency data.
• Rate Limiting — 60 req/min for reads, 10 req/min for writes per IP.

Requirements

• WordPress 5.8+ (tested up to 7.0)
• PHP 7.4+
• MySQL 5.7+ / MariaDB 10.3+
• Node.js 18+ (for building minified assets)

Installation

1. Download or clone this repository into your wp-content/plugins/ directory:

   wp-content/plugins/rivian-tire-guide/

2. Install build dependencies and build minified assets:

   cd wp-content/plugins/rivian-tire-guide
   npm install && npm run build

3. Activate the plugin via Plugins > Installed Plugins in the WordPress admin.
4. The plugin will automatically create the required database tables and run migrations.
5. Navigate to Tire Guide > Settings to configure display options and theme colors.
6. Add the shortcode [rivian_tire_guide] to any page or post.

Usage

Shortcodes

Tire Guide — Place on any page to display the full catalog:

[rivian_tire_guide]

With pre-filter attributes:

[rivian_tire_guide vehicle="R1" brand="Michelin" category="All-Season" size="275/65R20" sort="price-asc" 3pms="yes"]

User Reviews — Display all reviews by a specific user (via ?reviewer=ID URL param):

[rivian_user_reviews]

Write a Review — The review page. The plugin serves it at /tire-review/ (the slug is a setting) on its own, marked noindex. To control the page's SEO, create a WordPress page at that same slug with the shortcode in it: a published page at the review slug takes over from the built-in route, and your SEO plugin handles its title, description and indexing like any other page.

[rivian_tire_review]

Adding Tires

1. Go to Tire Guide > Add New in the WordPress admin.
2. Fill in tire specifications (brand, model, size, price, weight, etc.).
3. The efficiency score is calculated automatically via AJAX as you fill in specs.
4. Tires appear in the frontend guide immediately.

For bulk operations, use Tire Guide > Import / Export to import tires via CSV.

Comparison Page

The plugin registers a custom URL at /tire-compare/ (configurable in settings). Users select tires from the guide and compare specs side-by-side with best-value highlighting.

AI Tire Advisor

Settings → AI Tire Advisor. Add an Anthropic API key (or define RTG_ANTHROPIC_API_KEY in wp-config.php), pick a model (Claude Opus 5 by default), and set the per-visitor limit. Answers are cached (a day for picks and comparisons, thirty days for review summaries) and keyed on the catalog, so an edit to a tire or a new review refreshes them. With the advisor on and no key, "Help me choose" still works from the guide's rules; the review summaries and the compare paragraph need a key. Routes: POST /wp-json/rtg/v1/advise, GET /wp-json/rtg/v1/tires/{id}/review-summary, GET /wp-json/rtg/v1/compare-summary?ids=a,b.

What's New Page

The plugin registers /tire-guide/whats-new/, rendered inside the theme from WHATS-NEW.md at the plugin root. Write that file for owners, not developers: one ## version - date heading per release, an optional intro line, then bullets that open with a bold lead sentence. Skip releases with nothing visible. It is parsed once per plugin version (or file edit) and also served at GET /wp-json/rtg/v1/whats-new for the guide's modal.