# prathushan/wp-site-inspector-agent architecture

> Architecture diagram of the GitHub repository prathushan/wp-site-inspector-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prathushan/wp-site-inspector-agent
- Repository: https://github.com/prathushan/wp-site-inspector-agent

## Overview

##### Project Type & Purpose
- This is a **WordPress plugin** (monolithic codebase) that plugs into the WP Admin area.
- Purpose: scan themes/plugins, surface hooks/shortcodes/REST endpoints, detect/fix errors via AI, export reports.

##### Main Components
A. WordPress Core
- Hook registration, menu pages, REST API.
- Database (MySQL) for post types, plugin/theme data.
B. WP Site Inspector Plugin
1. **Entry Point** (`wp-site-inspector.php`)
– Registers admin menu, enqueues scripts/styles, hooks into AJAX.
2. **Admin UI Module** (`admin/class-admin-ui.php` + `admin/views/*.php`)
– Renders dashboard, scan forms, chatbot widget.
3. **Analyzer Module** (`admin/class-analyzer.php`)
– Uses WP filesystem APIs to crawl theme/plugin files, detect hooks/shortcodes.
4. **Backup & Export Module** (`admin/class-backup-export.php`, `includes/class-export-handler.php`)
– Takes `.bak` snapshots, exports `.xls` using PHPExcel (in `assets/libs`).
5. **Fix Agent Module** (`admin/class-fix-agent.php`)
– Parses error logs, calls external AI API, writes fixes, restores backups.
6. **Settings Module** (`admin/class-settings.php`)
– Manages BYOK (Bring Your Own Key) configuration and provider/model selection.
7. **Includes / Utility Handlers** (`includes/…`)
– AJAX handlers, email alerts (`class-email-handler.php`), logging, helper functions.
8. **Assets** (`admin/assets/`, `assets/libs/`)
– JS/CSS for interactive UI, third-party libraries for file export.
9. **Languages** (`languages/*.po/.mo`)
– i18n support for EN, DE, ES.
C. External Services
– **AI Providers** (OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter, WPSI-01).
– **Email SMTP** (for fatal error alerts).

##### Relationships & Data Flows
- **Admin Browser ↔ WP Core**
- Admin logs in, clicks “Site Inspector” menu.
- WP Core loads plugin’s admin UI.
- **UI ↔ AJAX Handlers**
- JS sends scan or chat/fix requests to `admin-ajax.php`.
- **AJAX Handlers → Plugin Modules**
- Handler routes requests to Analyzer or Fix Agent.
- Analyzer reads filesystem, WP DB, returns JSON.
- Fix Agent calls AI API, writes files, manages backups.
- **Plugin Modules ↔ External AI API**
- HTTP requests (REST) with user’s API key.
- **Plugin Modules ↔ Database**
- Reads post types, options (settings), logs scan/fix events (logger).
- **Export Module → File System**
- Creates `.xls`, saves to `wp-content/uploads` or streams download.
- **Error Handling**
- Logger writes to WP Debug log.
- Email Handler sends alerts.

##### Architectural Patterns & Principles
- Modular PHP classes per concern (Single Responsibility).
- WordPress Hook + AJAX-driven micro-endpoints.
- Backup-before-modify strategy for safe auto-fix.
- BYOK design for pluggable AI providers.
- MVC-like separation: Views (`admin/views`), Controllers (`ajax-handlers`), Models (filesystem + DB operations in classes).

##### Final Checklist
- [ ] Clear, named containers for WP Core vs Plugin.
- [ ] All plugin components (Admin UI, Analyzer, Fix Agent, Export, Settings, AJAX Handlers, Email, Logger).
- [ ] Database and File Storage nodes.
- [ ] External AI service providers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Admin Browser and WP Core
    AdminBrowser["Admin Browser"]:::external
    WPCore["WordPress Core"]:::core

    AdminBrowser -->|"click Site Inspector menu"| WPCore
    WPCore -->|"loads plugin entry"| EntryPoint

    %% Plugin Container
    subgraph "WP Site Inspector Plugin"
        direction TB
        EntryPoint["wp-site-inspector.php"]:::plugin
        AdminUI["Admin UI Module"]:::plugin
        Analyzer["Analyzer Module"]:::plugin
        BackupExport["Backup & Export Module"]:::plugin
        FixAgent["Fix Agent Module"]:::plugin
        Settings["Settings Module"]:::plugin
        AjaxUtils["AJAX & Utility Handlers"]:::plugin
        Assets["Assets (JS/CSS & Libs)"]:::plugin
        Languages["Languages (i18n)"]:::plugin
        Uninstall["uninstall.php"]:::plugin
        Docs["Docs & Licenses"]:::plugin
    end

    %% Database and File Storage
    DB["MySQL Database"]:::storage
    FileSystem["File System (uploads, backups)"]:::storage

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        OpenAI["OpenAI"]:::cloud
        Anthropic["Anthropic"]:::cloud
        Gemini["Google Gemini"]:::cloud
        DeepSeek["DeepSeek"]:::cloud
        OpenRouter["OpenRouter"]:::cloud
        WPSI01["WPSI-01"]:::cloud
    end

    %% Email SMTP
    SMTP["Email SMTP Service"]:::cloud

    %% Flows
    EntryPoint -->|"registers menu, enqueues"| AdminUI
    AdminUI -->|"renders views / JS"| Assets
    AdminUI -->|"AJAX requests"| AjaxUtils
    AjaxUtils -->|"route Scan Request"| Analyzer
    AjaxUtils -->|"route Fix Request"| FixAgent
    Analyzer -->|"read files + DB"| FileSystem
    Analyzer -->|"detect hooks/shortcodes"| Analyzer
    FixAgent -->|"backup-before-modify"| BackupExport
    BackupExport -->|"create .bak / .xls"| FileSystem
    FixAgent -->|"call AI Prompt"| OpenAI
    FixAgent -->|"call AI Prompt"| Anthropic
    FixAgent -->|"call AI Prompt"| Gemini
    FixAgent -->|"call AI Prompt"| DeepSeek
    FixAgent -->|"call AI Prompt"| OpenRouter
    FixAgent -->|"call AI Prompt"| WPSI01
    FixAgent -->|"write patches"| FileSystem
    FixAgent -->|"log events"| DB
    Settings -->|"store options"| DB
    AjaxUtils -->|"log errors"| DB
    AjaxUtils -->|"send alerts"| SMTP

    %% Bi-directional flows
    AdminUI <-->|"UI AJAX"| AjaxUtils

    %% Click Events
    click EntryPoint "https://github.com/prathushan/wp-site-inspector-agent/blob/main/wp-site-inspector.php"
    click AdminUI "https://github.com/prathushan/wp-site-inspector-agent/blob/main/admin/class-admin-ui.php"
    click Analyzer "https://github.com/prathushan/wp-site-inspector-agent/blob/main/admin/class-analyzer.php"
    click BackupExport "https://github.com/prathushan/wp-site-inspector-agent/blob/main/admin/class-backup-export.php"
    click AjaxUtils "https://github.com/prathushan/wp-site-inspector-agent/blob/main/includes/ajax-handlers.php"
    click Assets "https://github.com/prathushan/wp-site-inspector-agent/tree/main/assets/libs/"
    click Settings "https://github.com/prathushan/wp-site-inspector-agent/blob/main/admin/class-settings.php"
    click Uninstall "https://github.com/prathushan/wp-site-inspector-agent/blob/main/uninstall.php"
    click Docs "https://github.com/prathushan/wp-site-inspector-agent/blob/main/README.md"
    click Docs "https://github.com/prathushan/wp-site-inspector-agent/blob/main/readme.txt"
    click Docs "https://github.com/prathushan/wp-site-inspector-agent/blob/main/LICENSE-GPLv2.txt"
    click Docs "https://github.com/prathushan/wp-site-inspector-agent/blob/main/LICENSE-MIT.txt"
    click Languages "https://github.com/prathushan/wp-site-inspector-agent/tree/main/languages/"
    click AdminUI "https://github.com/prathushan/wp-site-inspector-agent/blob/main/admin/views/dashboard.php"
    click AdminUI "https://github.com/prathushan/wp-site-inspector-agent/blob/main/admin/views/backup.php"
    click AdminUI "https://github.com/prathushan/wp-site-inspector-agent/blob/main/admin/views/code-ai.php"
    click AdminUI "https://github.com/prathushan/wp-site-inspector-agent/blob/main/admin/views/ai-agent-ui.php"
    click BackupExport "https://github.com/prathushan/wp-site-inspector-agent/blob/main/includes/class-export-handler.php"
    click AjaxUtils "https://github.com/prathushan/wp-site-inspector-agent/blob/main/includes/class-email-handler.php"
    click AjaxUtils "https://github.com/prathushan/wp-site-inspector-agent/blob/main/includes/logger.php"
    click AjaxUtils "https://github.com/prathushan/wp-site-inspector-agent/blob/main/includes/helper-functions.php"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:1px;
    classDef plugin fill:#ABEBC6,stroke:#145A32,stroke-width:1px,stroke-dasharray: 5 5;
    classDef storage fill:#F9E79F,stroke:#B9770E,stroke-width:1px;
    classDef cloud fill:#D7BDE2,stroke:#512E5F,stroke-width:1px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:1px;
```
