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 wheels database — adding a wheel for a new vehicle makes it appear in the toggle with no extra configuration.
• Wheel Guide — A "Not sure which tire fits your Rivian?" panel above the cards lists every wheel per vehicle with its stock and alternate sizes, split into Factory wheels and Aftermarket setups.
• Third-Party Wheel Sizes — The guide can list a size Rivian never shipped (say, 18-inch tires on an R2) for owners running aftermarket wheels. A wheel marked Third-party in the admin makes its sizes "3rd-party wheels" sizes for that vehicle, unless a factory wheel also lists them. Those sizes are suffixed in the size menu, tire cards carry a lavender note with the wheel's fitment note in its tooltip, tire pages show a "Fits R2 · 3rd-party wheels" chip and a plain-language notice, the compare table and review page say it beside the size, and the advisor never recommends one unless the owner names that size.
• Load-Index Fitment — Every card, tire page and compare column is judged against the vehicle's minimum load index (R1 116, R2 112, both settings) and warns in red when a tire falls short. The warning wins over the third-party note when a tire earns both.
• Filter Bar — Search runs as you type. Below it, the vehicle switch and one pill per filter (Size, Brand, Category, Price, Warranty, 3PMS, OEM); a pill opens a popover with the options, or the slider with presets, and shows its value once set. On a phone the pill row scrolls sideways and any pill opens the full set as a bottom sheet with native pickers and a live "Show N tires" button.
• Smart Search — Word-prefix matching across brand, model, category and size, so "mich 275" finds Michelin tires in 275 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.
• Filter Summary — Set pills carry their value in accent, and the results line shows the count, the number of filters on, and Clear all.
• 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" link in the guide footer 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/.
• Write a Review — A link in the filter header to the review page, where a visitor picks a tire and reviews it with or without an account.

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 six optional detail ratings, the vehicle and the miles on the set. Tapping a star on a guide card opens the review page with that tire and star already set.
• 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.

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 Data admin page. Multiple Roamer entries can be assigned to one tire with weighted-average efficiency.
• Tire Cards — Blue mi/kWh pill 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, per vehicle: size must be a Rivian fitment, load index must clear that platform's floor (R1 116, R2 112, both settings), load range must be at least that platform's minimum (the R2 needs XL or higher, so an SL tire in an R2 size is a near miss), and the listing must be identifiable. Specs are parsed out of the product title when the feed doesn't supply them as fields.
• Brand Policy — By default the queue lists only the brands on the guide's own brand list: a listing from any other brand is judged and counted but never stored, and rows earlier runs kept for such brands are removed. The policy can be relaxed in Discovery settings to file uncovered brands under Near Misses or to surface them flagged.
• 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. The fits column names each vehicle a candidate is legal on, with "· 3rd-party" when that vehicle takes the size only on aftermarket wheels.
• 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 — A "Needs attention" list first (failed runs, pending reviews, the discovery queue, broken or missing links, missing images), then overview tiles (tires, reviews, affiliate coverage, Roamer coverage, average price), breakdowns by category/brand/size, Rivian Roamer real-world efficiency overview and top 5 rankings. 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, 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 per-vehicle minimum load index and load range.
• Wheels — Manage the wheel guide: name, stock and alternate sizes, image, vehicles, sort order, and whether the wheel is a Rivian factory wheel or a third-party setup with a one-sentence fitment note.
• 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.
• No Icon Font Shipped — Icons are Font Awesome 6 classes (fa-solid) rendered by the site's theme; the plugin enqueues no icon font of its own.

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.
• GET /wp-json/rtg/v1/feed — Full tire catalog JSON feed with ratings and Roamer real-world efficiency data.
• GET /wp-json/rtg/v1/whats-new — The parsed release notes the guide's Changelog dialog loads.
• POST /wp-json/rtg/v1/advise — Help me choose: three picks with reasons and trade-offs.
• GET /wp-json/rtg/v1/tires/{tire_id}/review-summary — "What owners say" for a tire page.
• GET /wp-json/rtg/v1/compare-summary?ids=a,b — The compare page's plain-words paragraph.
• 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). Without the param the page shows the signed-in visitor's own reviews, so a "My reviews" menu item can link the page's bare URL (default /user-reviews/); signed-out visitors are asked to sign in. Member names on a tire page link here. The page is styled like the tire page (breadcrumb, title, one card per review with the tire linked to its page) from its own stylesheet, frontend/css/user-reviews.css.

[rivian_user_reviews]

Saved Tires — A signed-in member's shortlist (the heart on cards and tire pages). The plugin serves it at /saved-tires/ (the slug is a setting) on its own, marked noindex; a published page at that slug with the shortcode takes over, so it can sit in a menu next to My Reviews:

[rivian_saved_tires]

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. Tires appear in the frontend guide immediately.

For bulk operations, use Tire Guide > Tools to import tires via CSV.

Wheel Guide and Third-Party Sizes

Tire Guide > Wheels holds one row per wheel: a name, the stock tire size, alternate sizes, an image, the vehicles it fits, and a sort order. Every vehicle-to-size rule in the plugin is derived from these rows: the vehicle toggle, the size menu, the load-index fitment checks, the advisor's candidates, the discovery qualifier and the review page's vehicle switch. There is no separate size list to maintain.

To list a size Rivian never offered, add a wheel, set Source to Third-party, enter the size it is run with as its stock size (and any others as alternates), tick the vehicle, and write a Fitment note such as "Needs an 8.5-inch or wider wheel around ET35. Some owners report light rubbing at full lock." The note shows under the tire page's third-party notice, in the card's info tooltip, and on the wheel guide card. A size is treated as third-party for a vehicle only when no factory wheel for that vehicle lists it; a factory listing always wins. Add the size to the sizes list and the size-to-diameter map under Settings > Dropdown Options so the tire page can show its overall diameter.

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 Changelog dialog.

Settings

Navigate to Tire Guide > Settings to configure:

• Tires Per Page — Number of tire cards per page (4-48).
• CDN Image Prefix — Optional CDN URL for image optimization.
• Compare Page Slug — Custom URL slug for the comparison page.
• User Reviews Page Slug — Custom URL slug for the user reviews page.
• Server-Side Pagination — Enable AJAX-based pagination for large catalogs.
• Theme Colors — 14 hex color values for full theme customization (accent, backgrounds, text, borders, stars).
• Dropdown Options — Manage brands, categories, sizes, diameters, load ranges, speed ratings, load index mappings, and size-to-diameter mappings.
• Affiliate Link Domains — Configure affiliate network domains for link classification.
• Analytics Retention — Data retention period (7-365 days).

File Structure

rivian-tire-guide/
├── rivian-tire-guide.php            # Main plugin entry point
├── CHANGELOG.md                     # Developer record: reasons, file names, tests
├── WHATS-NEW.md                     # Owner-facing release notes (rendered in the guide)
├── ROADMAP.md                       # Open items and what has shipped
├── uninstall.php                    # Cleanup on plugin deletion
├── package.json                     # Build tools (esbuild) and the Node test script
├── esbuild.config.mjs               # Build configuration
├── includes/
│   ├── class-rtg-activator.php      # Database creation & numbered migrations
│   ├── class-rtg-deactivator.php    # Deactivation cleanup
│   ├── class-rtg-database.php       # All database operations, caching, the vehicle and third-party size maps
│   ├── class-rtg-fitment.php        # Load-index and third-party wheel fitment rules (JS twin: modules/fitment.js)
│   ├── class-rtg-admin.php          # Admin UI, CSV import/export, settings, wheel editor
│   ├── class-rtg-frontend.php       # Shortcode rendering & asset enqueue
│   ├── class-rtg-ajax.php           # AJAX endpoints (ratings, reviews, analytics, filter options)
│   ├── class-rtg-rest-api.php       # REST API endpoints and the cached /feed
│   ├── class-rtg-rate-limiter.php   # Shared per-IP limiter for reviews and REST
│   ├── class-rtg-compare.php        # Comparison page routing & CSP headers
│   ├── class-rtg-tire-page.php      # /tires/{slug}/ landing pages
│   ├── class-rtg-tire-review.php    # /tire-review/ page and its shortcode
│   ├── class-rtg-theme-render.php   # Renders routed pages inside the theme; ad blocklist
│   ├── class-rtg-schema.php         # Schema.org JSON-LD structured data
│   ├── class-rtg-meta.php           # Per-tire meta, Open Graph & Twitter Cards
│   ├── class-rtg-whats-new.php      # What's new: notes parser, page, REST route
│   ├── class-rtg-advisor.php        # AI Tire Advisor: ranking, prompts, Claude client, routes
│   ├── class-rtg-roamer-sync.php    # Rivian Roamer efficiency data sync
│   ├── class-rtg-catalog-sync.php   # Tire Discovery: the daily catalog check
│   ├── class-rtg-catalog-source.php # Retailer source interface (+ class-rtg-catalog-source-cj.php)
│   ├── class-rtg-tire-qualifier.php # Discovery: spec parsing and qualification rules
│   ├── class-rtg-candidates.php     # Discovery: the review queue table
│   ├── class-rtg-catalog-presence.php, class-rtg-coverage.php, class-rtg-health.php
│   ├── class-rtg-price-sync.php, class-rtg-stale-prices.php, class-rtg-retailer.php
│   ├── class-rtg-link-sync.php, class-rtg-link-checker.php, class-rtg-tire-images.php
│   ├── class-rtg-lock.php           # Named locks for cron and migrations
│   └── class-rtg-mailer.php         # HTML email notifications
├── admin/
│   ├── views/                       # Admin page templates (14 views, incl. wheel-list / wheel-edit and tire-discovery)
│   ├── css/                         # Admin stylesheet (+ .min)
│   └── js/                          # admin-scripts.js, rtg-discovery.js, rtg-roamer.js
├── frontend/
│   ├── templates/                   # tire-guide, tire-page-content, compare, tire-review, user-reviews, whats-new
│   ├── css/                         # rivian-tires.css (+ .min)
│   └── js/
│       ├── rivian-tires.js          # Main entry point (ES modules, bundled)
│       ├── compare.js               # Comparison page (bundled, shares the guide's modules)
│       ├── tire-page.js             # Tire page interactions
│       ├── tire-review.js           # Review page (not bundled)
│       ├── user-reviews.js          # User reviews page script
│       ├── rtg-shared.js            # Shared URL validation & escaping
│       └── modules/                 # Focused ES modules
│           ├── state.js             # Global state, incl. the vehicle and third-party size maps
│           ├── helpers.js           # DOM utilities, debounce, icons
│           ├── validation.js        # Input sanitization & patterns
│           ├── allowed-domains.js   # Link domain allowlist
│           ├── analytics.js         # Click & search tracking
│           ├── cards.js             # Tire card rendering and the fitment slot
│           ├── fitment.js           # Load-index and third-party fitment (PHP twin: class-rtg-fitment.php)
│           ├── pricing.js           # Set-of-four price and freshness
│           ├── efficiency.js        # Efficiency badge helpers
│           ├── vehicle-memory.js    # Remembered vehicle toggle
│           ├── compare.js           # Compare checkbox & bar
│           ├── filters.js           # Filter UI, size menu, sorting, URL state
│           ├── ratings.js           # Card ratings: loading, stars, posting
│           ├── search.js            # Smart search autocomplete
│           ├── server.js            # Server-side pagination
│           ├── tooltips.js          # Info (i) notes, in the dialog shell
│           ├── image-modal.js       # Photo lightbox, in the dialog shell
│           ├── dialog.js            # The dialog shell every dialog is built on
│           ├── whats-new.js         # Changelog link + dialog
│           └── advisor.js           # Help me choose dialog
├── tests/
│   ├── bootstrap.php                # PHPUnit WordPress test bootstrap
│   ├── test-*.php                   # PHPUnit suites (database, activator, admin, ajax, fitment, advisor, discovery, sync, ...)
│   ├── test-validation.js           # Node: input validation
│   ├── test-*.mjs                   # Node: dropdown options, domain sync, fitment, pricing, efficiency
│   └── contract/                    # Plain-PHP contract checks (advisor, CJ lookup, health, what's new)
├── .phpcs.xml                       # PHP CodeSniffer config (WordPress standards)
└── .github/
    └── workflows/ci.yml             # CI: JS tests + build check, PHPUnit, PHP lint + contracts, PHPCS

Database Schema

The plugin creates 6 tables (all prefixed with wp_rtg_):

Table	Purpose
rtg_tires	Main tire catalog (38 columns)
rtg_ratings	User and guest reviews with moderation and optional detail ratings
rtg_wheels	Wheel guide: factory wheels and third-party setups (source, fitment_note), the source of every vehicle-to-size rule
rtg_click_events	Affiliate link click tracking
rtg_search_events	Search, filter and advisor analytics
rtg_tire_candidates	Tire Discovery review queue

Schema changes are managed via a numbered migration system (rtg_db_version option, currently v27).

Development

Build

npm install
npm run build          # One-time production build (minified JS/CSS, console stripped)
npm run build:watch    # Watch mode for development

Test

npm test               # Six Node suites: validation, dropdown options, domain sync, fitment, pricing, efficiency
php tests/contract/*.php   # Plain-PHP contract checks (no WordPress needed)

PHP tests require a WordPress test environment:

phpunit                # PHPUnit suites (350+ tests across 23 files)

PHP coding standards:

phpcs --standard=.phpcs.xml    # Run WordPress Coding Standards checks

CI

GitHub Actions runs on every push and PR:

• JavaScript unit tests, an esbuild build, and a check that the committed minified assets match the source
• PHPUnit against the WordPress test library (PHP 7.4, 8.0, 8.2)
• PHP syntax linting (PHP 7.4, 8.0, 8.2) plus the contract checks
• PHP coding standards (WPCS via PHPCS)

Security

This plugin follows WordPress security best practices:

• All database queries use $wpdb->prepare() with parameterized placeholders
• CSRF protection via nonces on all forms and AJAX mutations
• Input sanitization (sanitize_text_field, sanitize_email, sanitize_textarea_field, esc_url_raw, intval, etc.)
• Output escaping (esc_html, esc_url, esc_attr)
• Capability checks (manage_options) on all admin actions
• Rate limiting on review submissions (3 per 5 minutes per user/IP)
• Rate limiting on REST API endpoints (60/min reads, 10/min writes)
• URL domain allowlisting for affiliate, review, and image links
• Content-Security-Policy headers on the standalone comparison page
• HTML escaping on all dynamic content in JavaScript templates
• CSV upload MIME type validation via finfo
• Honeypot field for guest review spam prevention
• Shared URL validation module (rtg-shared.js) as single source of truth

For security concerns, see SECURITY.md.

License

Proprietary. All rights reserved by RivianTrackr.

Support

For issues, feature requests, or questions, please open an issue on this repository.