# System Patterns This file documents the architectural and design patterns used in the project. 2025-03-26 11:13:00 - Updated with development environment workflow patterns ## Development Environment Patterns ### Container Architecture * **Docker Composition** * WordPress (PHP-FPM) * Nginx web server * MariaDB database * phpMyAdmin utility * Shared volumes for persistence * Network isolation * Environment-based configuration ### Development Workflow Patterns * **Backup-Based Setup** * Production data backup creation * Local backup storage * Backup-based environment initialization * Consistent development environments * Offline development capability * **Script Organization** * Standardized naming conventions * Clear separation of concerns * Comprehensive error handling * User-friendly feedback * Modular script design ### Configuration Management * **Environment Variables** * Database credentials * WordPress settings * Development flags * Debug options * Site URLs * **Docker Volumes** * WordPress files * Database data * Configuration files * SSL certificates * Logs ### WordPress Integration * **Core Configuration** * wp-config.php management * Environment-based settings * Debug mode control * URL configuration * Security settings * **Plugin Management** * Controlled activation * Version management * Dependency handling * Update procedures * Compatibility checks ### Database Patterns * **Connection Management** * Environment-based credentials * Connection pooling * Error handling * Retry mechanisms * Timeout configuration * **Data Access** * WordPress WPDB wrapper * Prepared statements * Transaction support * Query optimization * Cache integration ### Security Patterns * **Development Security** * Disabled SSL requirement * Debug mode enabled * Error display active * Test data isolation * Local-only access * **Production Preparation** * SSL configuration ready * Error logging configured * Security headers prepared * Access controls defined * Data sanitization ### Testing Architecture * **Test Environment** * Isolated containers * Test-specific configuration * Data fixtures * Mock services * Debug capabilities * **Test Types** * Unit tests * Integration tests * E2E tests * Performance tests * Security tests ### Logging and Monitoring * **Log Management** * PHP error logs * WordPress debug log * Nginx access/error logs * Database logs * Container logs * **Monitoring** * Container health checks * Resource usage * Error tracking * Performance metrics * Security events ### Version Control * **Feature Branches** * Feature branches * Pull requests * Code review process * Continuous integration * Automated testing 2025-03-27 13:55:00 - Added WordPress Unit Testing Patterns ### Unit Testing Architecture * **Containerized Testing** * WordPress test environment inside Docker container * WordPress testing libraries installed in container * Database access from container * Shared file system via volume mounts * Consistent environment across developers * **Test Configuration** * PHPUnit configuration in phpunit.xml.dist * Bootstrap configuration in tests/bootstrap.php * WordPress test framework in /tmp/wordpress-tests-lib * Test database isolated from development database * Environment variables for configuration * **Test Patterns** * WP_UnitTestCase base class for WordPress-aware tests * Fixtures and factories for test data * Test suite organization by feature * Isolated test methods * Consistent validation patterns 2025-03-28 05:33:00 - Updated Test Configuration Patterns ### Test Configuration Patterns * **Environment-Specific Settings** * Docker-aware database configuration * Container-specific file paths * Environment variable integration * Separate test database * Isolated test framework files * **Framework Organization** * WordPress test framework in vendor directory * Composer-managed dependencies * Standardized configuration locations * Clear separation between test and development databases * Environment-aware path resolution [2025-04-02 10:08:00] - Added Child Theme Template Overrides Pattern ### Child Theme Template Overrides * **Pattern**: Override plugin template files by placing identically named files within a specific subdirectory structure in the active child theme. * **Usage**: Can be used to customize the appearance and surrounding content of pages generated by plugins. * **TEC Override Path**: `[child-theme-directory]/tribe-events/` (followed by the plugin's internal view structure, e.g., `community/edit-event.php`). * **Implementation**: Copy original template from plugin to child theme override path, then modify the copy. WordPress automatically loads the child theme version. * **Note (2025-04-02):** This approach was attempted for The Events Calendar: Community Events pages (`edit-event.php`, `event-list.php`) but was abandoned due to persistent content duplication and layout issues. Switched to using TEC CE shortcodes on dedicated pages instead. 2025-03-26 11:13:00 - Added development environment workflow patterns [2025-04-06 13:28:00] - Added NAS-Based Development Workflow Patterns ## NAS-Based Development Workflow (Added 2025-04-06) * **Remote Docker Environment:** * Docker containers (WordPress, DB, Nginx, etc.) run on a remote NAS device. * NAS provides centralized resources and potentially better performance than local machine. * **Local Code Editing:** * Source code (plugin, themes, scripts) is edited on the local development machine (laptop). * **Synchronization:** * `rsync` is used to synchronize changes from the local machine's project directory (`wordpress-dev`) to the corresponding directory on the NAS. * An exclusion file (`rsync-exclude.txt`) prevents syncing unnecessary files/directories (e.g., `.git`, `node_modules`, `vendor`, `backups`). * A dedicated script (`bin/sync-to-nas.sh`) automates the sync process. * **Remote Execution (SSH):** * Most management scripts (`setup-*.sh`, `verify-*.sh`, `reset-*.sh`, `manage-*.sh`, `logs.sh`, `cleanup.sh`) are executed *locally*. * These scripts internally use SSH (with key-based authentication) to connect to the NAS and execute Docker, WP-CLI, or filesystem commands within the project directory on the NAS. * Scripts require NAS connection details (IP, user) from a root `.env` file. * Scripts use the full path to executables like `docker-compose` on the NAS. * **Local E2E Testing:** * Playwright E2E tests are executed *locally* on the development machine. * The `baseURL` in `playwright.config.ts` is configured (via environment variable `NAS_WORDPRESS_URL`) to target the WordPress site running on the NAS IP address and port. [2025-04-07] - Added Composer via Volume Mount (NAS Setup - Paused) * **Pattern**: Mount Composer PHAR directly into container via `docker-compose.yml`. * **Usage**: Workaround when installing Composer during Docker image build fails or is unreliable. * **Implementation**: Download `composer.phar` locally (e.g., to `bin/`), add volume mount like `- ./bin/composer.phar:/usr/local/bin/composer` to the relevant service in `docker-compose.yml`. * **Note**: This pattern was implemented for the NAS-based setup which is currently paused.