OPA Commerce - Project Architecture & Documentation

Repository: https://github.com/opareklama/opa-commerce Core Objective: A modular, high-performance WooCommerce extension built for Unifight Gym. It provides advanced frontend capabilities (Sliders, Shop Builder, Custom Product Cards) with a deeply integrated Design System Engine, entirely managed from the WordPress backend.

1. Architectural Pattern

The plugin uses a strict Object-Oriented (OOP), Namespace-driven (OpaCommerce), and Modular architecture.

• No Global Namespace Pollution: Everything is scoped under OpaCommerce\.
• Centralized Bootstrapping: The main opa-commerce.php file only defines constants and calls the singleton OpaCommerce\Core\Plugin::instance().
• Modularity: Every distinct feature (e.g., Sliders, Product Cards) is separated into its own self-contained folder under /modules/.
• Security First: Strict defined('ABSPATH') checks on all files, and unified data sanitization through the Settings_Manager.

2. Directory Structure

opa-commerce/
│
├── core/
│   ├── Plugin.php                 // The main engine. Initializes modules and shortcodes.
│   └── Settings_Manager.php       // Centralized CRUD and strict sanitization for ALL plugin settings.
│
├── lib/
│   └── plugin-update-checker/     // (PUC) Handles automatic updates via GitHub.
│
├── modules/                       // All independent features live here.
│   ├── Bottom_Bar/
│   ├── Category_Slider/
│   ├── Design_System/             // Generates the global CSS variables.
│   ├── Product_Cards/             // Renders custom product loop cards.
│   ├── Product_Slider/
│   ├── Shop_Builder/              // Overrides the default WooCommerce archive.
│   └── Single_Product/            // Overrides the single product page layout.
│
└── opa-commerce.php               // The primary plugin file (Entry point).

3. Core Components

A. Settings Manager (core/Settings_Manager.php)

All data in the plugin is saved under a single WordPress option key: opa_commerce_settings.

• Sanitization Filter: Before data is saved, it passes through sanitize_settings(). This method explicitly checks array shapes and strips out unapproved data. (Note: Nested arrays like responsive styling are actively processed here).
• Usage: Any module can inject the $settings_manager via Dependency Injection to read values ($this->settings_manager->get('design_system')).

B. The Design System (modules/Design_System)

Acts as the central nervous system for styling. It allows the admin to set global variables (Primary Color, Border Radius, Card Backgrounds, Typography).

• Dynamic CSS Generator: It reads the settings and dynamically generates a block of CSS variables (:root { --opa-primary: #xxxxxx; }) and injects it into the <head> of the frontend.

C. WooCommerce Overrides

• Shop Builder: Intercepts WooCommerce's default woocommerce_content and replaces it with a custom grid, pagination, and layout settings configured in the backend.
• Single Product: Hooks into woocommerce_single_product_summary to rearrange, hide, or restyle elements (Gallery, Add to Cart, Title, SKU) based on backend toggles.

D. Advanced Sliders (Shortcode Driven)

Both Category Sliders and Product Sliders are built dynamically:

1. Users create unlimited sliders in the backend via a Javascript-driven UI (slider-admin.js).
2. The UI uses the WordPress Media Uploader for custom fallback images.
3. It generates a unique shortcode (e.g., [opa_category_slider id="slider_123"]).
4. The frontend renders them using Slick Slider, hooking into the specific layout configurations saved for that ID.

4. Development & "Future Proofing" Rules

If giving this codebase to ChatGPT or another developer, enforce these rules to maintain the integrity of the architecture:

1. Never use standard WordPress settings fields loosely: Any new setting MUST be added to the $settings_manager mapping and sanitized correctly in Settings_Manager.php -> sanitize_settings().
2. Strict OOP: No procedural functions outside of the main opa-commerce.php file. Create a class inside a Module, and initialize it inside Plugin.php's load_modules() method.
3. Enqueueing Assets: Always enqueue CSS and JS inside the respective Module's class using wp_enqueue_script or wp_enqueue_style. Only enqueue assets on the specific admin pages where they are needed to prevent backend bloat.
4. JS Data Passing: When passing PHP arrays to JavaScript (like WooCommerce categories), ensure the array is strictly indexed (array_values()) so wp_localize_script correctly encodes it as a JS Array, preventing .map() fatal errors.
5. Updates: The plugin uses GitHub for distribution via YahnisElsts's plugin-update-checker. The GitHub repository is Public, so no authentication token is required in the code. To release an update, simply bump the version in opa-commerce.php and push to the master branch.