Architecture

BallinKit is built on a modular WordPress plugin architecture tightly integrated with WooCommerce. The frontend designer is powered by Fabric.js, and the server-side compositing uses ImageMagick/GD2.

Request Flow — Customer Design to Order

1. Product Page: Customer clicks "Customize Design" — redirected to /designer-studio/?product_id={id}
2. Designer Studio Load: PHP reads the kit_product config, passes it as window.KIT_CONFIG JSON to the page
3. Canvas Init: customizer.js initializes a Fabric.js canvas, loads base images, applies color fills, and renders any template
4. Customer Designs: Text/image layers added via Fabric.js. Each action is tracked in an undo/redo history stack
5. Add to Cart: JS calls exportDesign() to serialize canvas state to JSON, then calls POST /kit-customizer/v1/save-preview to generate and save a composite preview image server-side
6. WooCommerce Cart: The design JSON and preview URL are added to cart item metadata via KIT_Cart
7. Checkout: KIT_Order_Handler::save_design_to_order() fires on woocommerce_checkout_create_order_line_item — persists all design meta to the order item
8. Order Display: KIT_Order_Handler::display_design_preview() fires on woocommerce_before_order_itemmeta — renders the design card in WooCommerce admin
9. License Webhook: KIT_Webhook_Dispatcher sends order events to the BallingKit License Portal for license generation

REST API Namespace

All plugin REST routes use the namespace kit-customizer/v1 (accessible at /wp-json/kit-customizer/v1/):

• POST /preview — Generate composite preview, returns base64 image
• POST /save-preview — Generate and save preview to disk, returns URL
• POST /upload — Upload customer logo/image, returns URL
• GET /fonts — List available fonts from manifest
• GET /products/{slug}/config — Get product canvas configuration
• GET /templates — List all published templates
• POST /templates/save — Save new/edit template (admin only)
• DELETE /templates/{id} — Delete template (admin only)
• POST /designs/save — Save user design draft
• GET /designs — Get current user's saved designs
• POST /designs/delete — Delete a saved design
• GET /order-items/{id}/design — Get design data for an order item (admin)

JavaScript Architecture (customizer.js)

The designer is a single JavaScript class instantiated on page load. Key properties and methods:

• this.canvas — Fabric.js canvas instance
• this.currentView — Active view key (e.g. "front")
• this.viewStates — Saved canvas state per view
• this.history / this.historyIndex — Undo/redo stack
• this.referenceImage — Stored reference image metadata (not a canvas object)
• this.baseScale — Canvas scale factor for responsive display
• exportDesign() — Serializes all view states to the design JSON payload
• loadView(viewKey) — Switches the canvas to a different view
• getUserLayers() — Returns all user-created canvas objects (excludes base/color/pattern/overlay system layers)
• addProductReferenceImage(file, dataUrl) — Stores reference image as metadata, shows preview card