AI Site Doctor

The only WordPress plugin that scans your entire site and explains every problem in plain English — free, on any host.

Every existing WordPress tool shows you raw data. AI Site Doctor translates it into plain English and tells you the exact fix.

---

Features (Phase 1 — Core Free)

1. Full Site Scanner

• Runs all checks on demand from the admin dashboard
• Stores a unified issue list with severity: critical / warning / info
• One-click "Run Full Scan" button triggers all modules below

2. AI Error Diagnosis

• Auto-detects PHP error log path (WP_DEBUG_LOG, common server paths)
• Parses, deduplicates, and counts repeated errors
• Sends each unique error to the Claude API and returns:
  • Plain English explanation
  • Root cause (plugin / theme / WP core)
  • Severity level
  • Step-by-step fix instruction
  • Whether it is safe to auto-fix
• Free tier: 25 AI diagnoses per month (resets monthly)

3. Site Health Score (A–F)

• Grades the site on: PHP version, WordPress version, memory limit, WP_DEBUG status, SSL, file permissions, database connection
• Stores 4-week score history for trend tracking
• Integrates alongside WordPress native Site Health

4. Plugin Health Checker

• Flags plugins not updated in 2+ years (abandoned = security risk)
• Flags plugins not tested with your current WordPress version
• Uses WordPress.org Plugins API — no API key required
• Full CVE scanning available in the Security Essentials add-on

5. Plugin Bloat Detector

• Measures JS + CSS payload loaded by each plugin on the front end
• Ranks plugins from highest to lowest page-load cost
• Example: "Slider Revolution loads 340 KB of assets on every page."

6. Update Risk Scorer

• Fetches changelog from WordPress.org before showing any plugin update
• Claude API reads the changelog for breaking-change keywords
• Scores each pending update: Safe / Caution / High Risk
• Falls back to a major-version heuristic when AI is unavailable

7. Image Size Audit

• Finds all Media Library images over 500 KB
• Shows dimensions, file size, and which published posts/pages use each image
• Sorted by file size — largest first

8. Alt Tag Auditor

• Scans the Media Library for attachments missing _wp_attachment_image_alt
• Scans all published post/page content for <img> tags with empty or missing alt
• SEO impact score per image: High / Medium / Low
• Inline editor: type and save alt text per image directly from the plugin dashboard

9. Basic SEO Checks (Site-Wide)

Checks every published post and page for:

• Missing meta description (Yoast / RankMath / AIOSEO compatible)
• Missing or multiple H1 headings
• noindex set on public-facing pages
• Thin content (under 300 words)
• No images in post
• No internal links
• Duplicate title tags across the site

10. Broken Link Report

• Crawls up to 100 published URLs
• HEAD-checks all <a href> links (internal + external)
• Flags: 404, 5xx errors, redirect chains longer than 2 hops
• Results cached in a custom DB table with last-checked timestamp

11. Manual Email Report

• "Send Report Now" button sends a formatted HTML + plain-text email to the admin address
• Includes health grade, issue counts, and plain English fix for each issue

---

Tech Stack

Layer	Technology
Language	PHP 8.0+
AI Model	Claude API (claude-sonnet-4-6)
AI Output	Structured JSON only
Dashboard UI	React via @wordpress/scripts
Styling	CSS (Dashicons for icons)
REST API	WordPress REST API (ai-site-doctor/v1)
Licensing	Freemius SDK (production) / stub (development)
CVE Data	WordPress.org Plugins API (no key required)
DB Tables	3 custom tables: health scores, broken links, scan results

---

REST API Endpoints

All endpoints require manage_options capability and use the wp_rest nonce.

Method	Endpoint	Description
POST	/ai-site-doctor/v1/scan	Run a full site scan
GET	/ai-site-doctor/v1/scan/results	Get last scan results
GET	/ai-site-doctor/v1/health-score	Get 28-day score history
GET	/ai-site-doctor/v1/alt-tags	Get full alt tag audit
POST	/ai-site-doctor/v1/alt-tags/{id}	Save alt text for an attachment
POST	/ai-site-doctor/v1/report/send	Send email report now
GET	/ai-site-doctor/v1/settings	Get current settings
POST	/ai-site-doctor/v1/settings	Save API keys
GET	/ai-site-doctor/v1/update-risk/{slug}	Get update risk for a plugin

---

Project Structure

ai-site-doctor/
├── ai-site-doctor.php              # Plugin bootstrap
├── uninstall.php                   # Full data cleanup on uninstall
├── readme.txt                      # WordPress.org listing
├── freemius/                       # Freemius SDK (add before production)
├── includes/
│   ├── class-loader.php            # Boots all classes and hooks
│   ├── class-db-tables.php         # Creates custom DB tables on activation
│   ├── class-ai-diagnosis.php      # Claude API integration
│   ├── class-scanner.php           # Full-scan orchestrator
│   ├── class-error-reader.php      # PHP error log parser + AI diagnosis
│   ├── class-health-score.php      # A–F site health scorer
│   ├── class-plugin-cve.php        # Patchstack CVE checker
│   ├── class-plugin-bloat.php      # JS/CSS payload per plugin
│   ├── class-update-risk.php       # Plugin update risk scorer
│   ├── class-image-audit.php       # Oversized image finder
│   ├── class-alt-scanner.php       # Alt tag audit + save
│   ├── class-seo-checker.php       # Site-wide SEO checks
│   ├── class-broken-links.php      # Broken link crawler
│   ├── class-email-report.php      # HTML + plain-text email report
│   └── class-rest-controller.php   # All REST API routes
├── admin/
│   └── class-admin-menu.php        # WP admin menu + asset enqueuing
└── assets/
    ├── src/                        # React source
    │   ├── index.js
    │   ├── App.js
    │   ├── api.js
    │   ├── components/
    │   │   ├── Sidebar.js
    │   │   ├── IssueRow.js
    │   │   └── IssueBadge.js
    │   ├── pages/
    │   │   ├── Dashboard.js
    │   │   ├── Errors.js
    │   │   ├── AltTags.js
    │   │   ├── Seo.js
    │   │   └── Settings.js
    │   └── style.css
    └── build/                      # Compiled output (run npm run build)

---

Local Development Setup

Requirements

• PHP 8.0+
• WordPress 6.3+
• Node.js 18+

Install

# 1. Clone into your WP plugins directory
git clone git@github-bilal:sahibbilal/ai-site-doctor.git wp-content/plugins/ai-site-doctor

# 2. Install and build React assets
cd wp-content/plugins/ai-site-doctor
npm install
npm run build

# 3. Activate the plugin in WP Admin → Plugins

# 4. Optionally add your Claude API key in AI Site Doctor → Settings
#    - Claude API key: console.anthropic.com
#    - Without the key, all scans still run — you just won't get AI explanations

Development Watch Mode

npm start   # Rebuilds assets on every file save

---

WordPress.org Compliance

• All PHP files protected with defined('ABSPATH') || exit
• All output escaped (esc_html, esc_url, esc_attr)
• All input sanitized via REST API sanitize_callback args
• All DB queries use $wpdb->prepare() or $wpdb->insert()
• All functions, options, hooks, constants prefixed with aisd_ / AISD_
• Text domain: ai-site-doctor throughout
• No premium code in the free ZIP (Freemius handles stripping)
• Full data cleanup in uninstall.php
• External services disclosed in readme.txt: Claude API (optional), WordPress.org Plugins API

---

Roadmap

Phase 2 — Core Pro

• Unlimited AI diagnoses
• Scheduled daily auto-scan (WP-Cron)
• One-click auto-fix with rollback
• Diff preview before any fix
• AI Chat Assistant (context-aware, 30-day memory)
• PageSpeed AI Explainer
• AI Alt Tag Generator (Claude vision)

Add-on Modules

Add-on	Price
DB Doctor	$7/site/month
Content Auditor	$7/site/month
WooCommerce Health	$9/site/month
Security Essentials	$7/site/month
Agency Toolkit	$19/month unlimited sites

---

Author

Bilal Mahmood — Senior Full Stack WordPress Developer
bilalmahmood.dev · GitHub @sahibbilal

---

License

GPL v2 or later — see LICENSE