care-book-block-ultimate/specs/001-wordpress-plugin-para/research.md

Research: WordPress Plugin para Controlo Seguro de Agendamentos KiviCare

Feature: WordPress Plugin para Controlo Seguro de Agendamentos KiviCare
Date: 2025-09-10
Research Phase: Technical decisions and best practices

Key Technical Decisions

1. CSS-First Approach vs PHP Filtering

Decision: Hybrid approach - CSS-first for immediate hiding, PHP hooks for data filtering
Rationale: Previous versions failed due to shortcode conflicts. CSS provides immediate visual hiding while PHP hooks ensure clean data without conflicts
Alternatives considered:

• Pure CSS approach (insufficient - doesn't prevent form submissions)
• Pure PHP hooks (caused instability in previous versions)
• Theme modification (not portable across themes)

2. Database Storage Strategy

Decision: Custom WordPress table wp_care_booking_restrictions
Rationale: Clean separation from KiviCare data, survives plugin updates, optimized indexes
Alternatives considered:

• WordPress options table (not scalable for large datasets)
• KiviCare database modification (breaks on updates)
• External database (adds complexity)

3. WordPress Integration Pattern

Decision: Standard WordPress plugin with hooks and filters
Rationale: Follows WordPress best practices, compatible with plugin ecosystem
Alternatives considered:

• Must-use plugin (too intrusive)
• Theme functions (not portable)
• Custom solution outside WordPress (breaks ecosystem)

4. KiviCare Integration Strategy

Decision: Hook into KiviCare's WordPress filters and actions, not direct database access
Rationale: Maintains compatibility with KiviCare updates, respects plugin boundaries
Alternatives considered:

• Direct database queries (brittle to schema changes)
• KiviCare code modification (impossible to maintain)
• API interception (complex and fragile)

5. Admin Interface Framework

Decision: Native WordPress admin with AJAX for real-time updates
Rationale: Consistent with WordPress UX, no additional dependencies, familiar to users
Alternatives considered:

• React admin interface (overkill for this functionality)
• Custom framework (reinventing wheel)
• Third-party admin framework (additional dependency)

6. Performance Optimization Strategy

Decision: WordPress transients for caching with selective invalidation
Rationale: Built-in WordPress caching, automatic expiration, integrates with object cache
Alternatives considered:

• File-based caching (not portable across hosting)
• Redis/Memcached direct (not always available)
• No caching (performance impact)

7. Error Handling and Recovery

Decision: Graceful degradation with detailed WordPress debug logging
Rationale: System continues working if KiviCare is unavailable, detailed logs for troubleshooting
Alternatives considered:

• Hard failures (breaks website)
• Silent failures (difficult to debug)
• External error tracking (additional dependency)

WordPress-Specific Best Practices Research

Plugin Architecture

• Activation/Deactivation hooks: For database table creation/cleanup
• Uninstall hook: For complete data removal when plugin is deleted
• WordPress coding standards: PSR-4 autoloading, proper sanitization
• Security: Nonces for forms, capability checks, prepared statements

Database Schema Design

• Indexes: Primary key on id, composite index on (restriction_type, target_id)
• WordPress prefixes: Use $wpdb->prefix for table names
• Data types: WordPress-compatible field types and constraints
• Migration strategy: Version checks and schema updates

Frontend Integration

• wp_enqueue_script/style: Proper asset loading with dependencies
• wp_localize_script: For passing PHP data to JavaScript
• WordPress AJAX: wp_ajax_* actions for admin interface
• Conditional loading: Only load admin assets in admin, frontend assets on frontend

Caching Strategy

• WordPress Transients API: set_transient/get_transient for temporary data
• Object Cache: Integration with wp_cache_* functions
• Cache invalidation: Clear related caches when restrictions change
• Plugin compatibility: Works with popular caching plugins

Performance Considerations

Database Optimization

• Query optimization: Use WordPress $wpdb with prepared statements
• Index strategy: Optimize for common query patterns
• Batch operations: For bulk restriction updates
• Connection pooling: Rely on WordPress database connection management

Frontend Performance

• Asset minification: Minified CSS/JS for production
• Conditional loading: Load assets only when needed
• Cache-friendly: Generate cache-friendly CSS selectors
• No render blocking: Non-critical CSS loaded asynchronously

Security Analysis

WordPress Security Best Practices

• Data sanitization: sanitize_text_field, intval for all inputs
• Data validation: Validate all form inputs before database operations
• Capability checks: current_user_can for all admin actions
• Nonces: wp_nonce_field for all forms, wp_verify_nonce for validation
• SQL injection prevention: Always use $wpdb->prepare

KiviCare Integration Security

• Hook priorities: Use appropriate priorities to avoid conflicts
• Data filtering: Filter data, don't modify KiviCare's database
• Capability respect: Respect KiviCare's user capabilities
• Plugin detection: Check if KiviCare is active before integration

Compatibility Analysis

WordPress Version Compatibility

• Minimum version: WordPress 5.0+ for block editor and modern APIs
• PHP version: PHP 7.4+ for modern syntax and performance
• MySQL version: MySQL 5.7+ for modern database features

KiviCare Plugin Compatibility

• Version support: KiviCare 3.0.0+ for stable hook system
• Hook compatibility: Use documented hooks where available
• Graceful degradation: Handle missing hooks gracefully
• Update resilience: Avoid depending on internal KiviCare functions

Theme and Plugin Compatibility

• Popular caching plugins: WP Rocket, W3 Total Cache, WP Super Cache
• Popular themes: Compatibility with major WordPress themes
• Page builders: Elementor, Gutenberg, classic editor
• Other healthcare plugins: Avoid conflicts with similar functionality

Research Conclusions

All technical unknowns have been resolved with specific implementation strategies that address the critical stability requirements learned from previous versions. The hybrid CSS-first + PHP hooks approach provides both immediate visual feedback and robust data filtering while maintaining system stability.

Status: ✅ All NEEDS CLARIFICATION items resolved
Next Phase: Phase 1 - Design & Contracts