# 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