wp-recache/docs/plans/2026-09-13-wprecache-design.md

# WP Recache — Open Source Performance Plugin

## Overview

Create a commercial-grade, open source (GPL-2.0+) WordPress performance plugin providing page caching, file optimization, and image optimization. Features are written from specification, never derived from any existing plugin's source code.

## Specification-First Methodology

### Rules

1. **No code reuse.** Never copy, paste, or adapt PHP/JS/CSS from any existing performance plugin.
2. **Feature specs only.** Features are specified from a *user perspective* (UI behavior, options, output), not from anyone's implementation.
3. **Independent implementation.** All code written from scratch using WordPress APIs and standard libraries.
4. **Documentation trail.** Keep records of the specification process to prove independent development.

### What We Study (User Perspective)

- Admin UIs of established performance plugins: what settings exist, what they control
- Frontend output: what HTML/JS/CSS changes appear after activation
- Behavior: when cache clears, what gets optimized, what's excluded by default
- Performance: what metrics improve

### What We Ignore

- PHP source code structure
- Internal class/function naming
- Specific implementation patterns
- Hook naming conventions

## Feature Specifications

### 1. Page Cache

**User-facing behavior:**
- On first anonymous visit, generates static HTML file
- Subsequent anonymous visits serve the static file directly
- Cache auto-purges when content is published/updated
- Manual purge available from admin bar and settings page
- Excludes logged-in users, cart/checkout pages, specific URLs
- Separate cache for mobile devices (optional)
- Preload/crawl sitemap to warm cache

**Technical approach (independent implementation):**
- Use WordPress `advanced-cache.php` drop-in
- Output buffering via `ob_start()` / `ob_get_contents()` / `ob_end_flush()`
- Cache files stored in `wp-content/cache/`
- Serve cached files via direct file read before WordPress loads
- Use WordPress rewrite rules for cache detection

### 2. File Optimization — CSS

**User-facing behavior:**
- Minify CSS files (remove whitespace, comments)
- Combine CSS files into fewer requests
- Defer non-critical CSS loading
- Remove unused CSS (RUCSS — Remove Unused CSS)
- Inline critical CSS for above-the-fold content
- Async CSS loading

**Technical approach:**
- Use CSS minification library (e.g., `natanielrodman/css-minify` or similar)
- Parse CSS to identify critical path selectors
- Output buffering to detect and modify `<link>` tags
- Generate critical CSS via headless browser or parser

### 3. File Optimization — JavaScript

**User-facing behavior:**
- Minify JavaScript files
- Combine JavaScript files
- Defer JavaScript loading (load after HTML parsed)
- Delay JavaScript execution (load on user interaction)
- Remove jQuery Migrate
- Delay inline scripts

**Technical approach:**
- Use JavaScript minification (e.g., `tedivm/jshrink` or similar)
- Output buffering to modify `<script>` tags
- Add `defer` or `async` attributes
- Wrap scripts in event listeners for delay functionality

### 4. Image Optimization

**User-facing behavior:**
- Lazy load images (load when entering viewport)
- Convert images to WebP/AVIF format
- Optimize image compression
- Add missing width/height attributes (CLS prevention)
- Placeholder images while loading

**Technical approach:**
- Use `loading="lazy"` attribute (native lazy loading)
- Use WordPress `wp_image_editor` APIs for format conversion
- Use Imagick/GD for compression
- Generate WebP/AVIF variants on upload

### 5. Additional Features

**Critical CSS:**
- Generate critical CSS for above-the-fold content
- Inline critical CSS, defer full stylesheet
- Per-page critical CSS generation

**Preload:**
- Preload key requests (fonts, critical resources)
- DNS prefetch for external domains
- Prefetch for likely next pages

**Database Optimization:**
- Clean post revisions
- Clean auto-drafts
- Clean trashed posts
- Optimize database tables

## Architecture

### Plugin Structure

```
wp-recache/
├── wp-recache.php                 # Main plugin file
├── uninstall.php                  # Clean uninstall
├── composer.json                  # Dependencies
├── readme.txt                     # WordPress.org readme
├── assets/
│   ├── css/
│   │   └── admin.css              # Admin UI styles
│   └── js/
│       └── admin.js               # Admin UI scripts
├── includes/
│   ├── Activator.php              # Plugin activation
│   ├── Deactivator.php            # Plugin deactivation
│   ├── Plugin.php                 # Main plugin class
│   ├── Admin/
│   │   ├── Admin.php              # Admin functionality
│   │   ├── Settings.php           # Settings page
│   │   └── Assets.php             # Admin assets
│   ├── Cache/
│   │   ├── WPCache.php            # Core page cache
│   │   ├── Purge.php              # Cache purge logic
│   │   └── Preloader.php          # Cache preloading
│   ├── Optimization/
│   │   ├── CSS/
│   │   │   ├── Minify.php         # CSS minification
│   │   │   ├── Combine.php        # CSS combination
│   │   │   └── CriticalCSS.php    # Critical CSS generation
│   │   ├── JS/
│   │   │   ├── Minify.php         # JS minification
│   │   │   ├── Combine.php        # JS combination
│   │   │   └── Defer.php          # JS defer/delay
│   │   └── RemoveUnusedCSS.php    # RUCSS
│   ├── Media/
│   │   ├── Lazyload.php           # Image lazy loading
│   │   ├── ImageFormat.php        # WebP/AVIF conversion
│   │   └── ImageOptimize.php      # Image compression
│   ├── Database/
│   │   └── Optimizer.php          # Database cleanup
│   └── Common/
│       ├── FileSystem.php         # File system utilities
│       ├──钩子/钩子.php           # Hook utilities
│       └── HTTP.php               # HTTP utilities
├── views/
│   ├── admin-settings.php         # Settings page template
│   └── admin-bar.php              # Admin bar menu
└── languages/
    └── wp-recache.pot             # Translation template
```

### Key Design Decisions

1. **No vendor dependencies for core features.** Use WordPress built-in APIs wherever possible.
2. **Modular architecture.** Each feature (cache, CSS, JS, images) is independent and can be disabled.
3. **WordPress standards.** Follow WordPress coding standards and hook system.
4. **Performance first.** Minimal overhead, no unnecessary database queries.

## Implementation Strategy

### Phase 1: Core Page Cache
- Implement `advanced-cache.php` drop-in
- Output buffering for HTML generation
- Cache file management (create, serve, purge)
- Admin settings page (basic)
- Admin bar purge button

### Phase 2: File Optimization
- CSS minification
- JS minification
- CSS/JS combination
- Defer/delay scripts
- Critical CSS generation

### Phase 3: Image Optimization
- Lazy loading
- WebP/AVIF conversion
- Image compression
- CLS prevention (width/height)

### Phase 4: Advanced Features
- Remove unused CSS
- Database optimization
- Preloading
- CDN support

## Legal Considerations

1. **Document everything.** Keep records of the specification process.
2. **Never access third-party plugin source code** while implementing.
3. **Use different naming.** Don't reuse prefixes or naming from existing plugins.
4. **Independent architecture.** Design your own class structure.
5. **Different defaults.** Choose different default settings where possible.

## Open Source Strategy

1. **License:** GPL-2.0-or-later (same as WordPress)
2. **Repository:** GitHub with public access
3. **WordPress.org:** Submit to plugin directory
4. **Community:** Accept contributions, maintain active development
5. **Commercial model:** Open core with premium features or SaaS add-ons

## Success Criteria

1. Feature set competitive with established commercial performance plugins: page cache, file optimization, image optimization
2. No code overlap with any existing plugin (verified by code review)
3. Performance benchmarks comparable to or better than established commercial solutions
4. Clean, maintainable code following WordPress standards
5. Active open source community