208 lines
No EOL
7.3 KiB
Markdown
208 lines
No EOL
7.3 KiB
Markdown
# 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. |