Client Sync: Plugin Structure

This is an overview of the Client Sync plugin's structure designed for another developer to understand how the components fit together for further development.

This technical overview is designed for developers who need to extend, debug, or contribute to the Client Sync plugin. It outlines the architectural patterns, data flow, and development standards used throughout the monorepo.

Client Sync: Technical Architecture Overview

Client Sync is a high-performance booking system built on a Dimension-based architecture. It prioritizes database efficiency and user experience by utilizing custom SQL tables for availability and React-based applications for complex visual editors.

1. Monorepo Structure

The project is organized into a single repository to manage the shared core logic alongside version-specific (Free vs. Pro) features.

Text

client-sync-monorepo/
├── src/
│   ├── shared/   # Core classes, database logic, and common assets used by both versions.
│   ├── free/     # Entry point and specific logic for the WordPress.org version.
│   └── pro/      # Pro-only modules (Memberships, Google Sync, Form Builder).
├── tests/        # PHPUnit and Jest test suites.
├── build.sh      # Bash utility for compiling assets and packaging the plugin.
└── webpack.config.js # Asset bundling for React applications.

2. Architecture & Components

A. The Dependency Graph (PHP)

The plugin initialization starts at src/shared/includes/core/class-plugin.php. It follows a decoupled pattern where managers handle specific logic:

  • Database_Manager: Handles all schema creation and direct SQL queries.

  • PostType_Manager: Manages CPT registrations and Admin UI (meta boxes/columns).

  • Calendar_Data_Provider: The central engine that fetches UTC slots and formats them for FullCalendar display.

  • Module_Manager (Pro): Dynamically discovers and loads Pro modules that implement the Module_Interface.

B. The Frontend Stack

Client Sync uses a Hybrid JS architecture:

  • React Apps: Located in src/assets/src/. These are standalone applications compiled by @wordpress/scripts.

    • booking-form: The main customer interface.

    • faceted-booking: A multi-select search interface.

    • manage-slots: An admin-side visual availability editor.

    • timeline-viewer: A horizontal resource visualization tool.

  • jQuery Modules: Located in src/assets/js/. Used for lightweight WordPress admin integrations (e.g., color pickers, custom dropdowns).

3. Data Persistence Layer

To avoid the performance bottlenecks of the wp_postmeta table, Client Sync utilizes 5 custom tables:

  1. clisyc_time_slots: Stores individual availability and blocked time segments.

  2. clisyc_slot_dimensions: A many-to-many map linking slots to specific items (Services, Staff, etc.).

  3. clisyc_bookings: Links appointments to specific database slots.

  4. clisyc_relationships: Stores the "Valid Path" graph between items.

  5. clisyc_graph_nodes: An index used for the visual Relationship Graph.

4. The "Dimension" Engine logic

The most critical logic is the Intersection Check.

  1. Generation: The Cron class pulls schedules from a Primary Dimension (the anchor) and all Resource Dimensions (the constraints).

  2. Intersection: Availability is only written to the database if a time is available in all required dimensions.

  3. Validation: When a booking is submitted, the Form_Handler uses a MySQL Transaction with a Row Lock (FOR UPDATE) to check capacity and prevent race conditions.

5. REST API & AJAX

The system relies on a robust internal API:

  • Namespace: wp-json/clisyc/v1/

  • Endpoints:

    • /slots: Fetches time slots based on start/end range and dimension filters.

    • /filter-options: Returns available items for the search dropdowns/checkboxes.

    • /dimensions/graph: Load/Save logic for the visual node editor.

    • /price: Real-time calculation for multi-day rental costs.

6. Development Workflow

Build System

The project uses build.sh to coordinate the move from source to production:

  • npm run build: Compiles React source into dist folders.

  • ./build.sh free: Packages the core plugin.

  • ./build.sh pro: Packages the Pro add-on.

Testing

  • Backend: Run composer test for PHPUnit unit tests.

  • Frontend: Run npm run test:js for Jest/React Testing Library components.

  • Setup: First-time setup requires ./build.sh test-setup to create the temporary WordPress environment.

7. Security Standards

  • Input: All data is sanitized via src/shared/includes/utility/class-sanitizer.php.

  • Output: Strict use of wp_kses and esc_html in all PHP views.

  • Requests: All state-changing actions require nonces and capability checks (manage_options or edit_posts).

  • Rate Limiting: Public REST endpoints utilize Security_Helper::check_rate_limit to prevent scraping.

Developer Tip: When modifying the Relationship Graph or Form Builder, always use Functional State Updates in React (setFields(prev => ...)) to avoid stale closures during asynchronous callbacks like the WordPress Media Manager.