Custom Round Buttons – 1″ Diameter

Developer starting point

This baseline links the custom round-button catalog item to the reviewed Print Forge implementation. It does not claim that a design upload, customization, render, artwork artifact, print job, vendor dispatch, shipment, or physical product has been exercised.

High-Level Architecture

The main bootstrap file is athenian-print-forge.php. It defines constants, loads helper functions, requires the major service and shortcode files, and then boots runtime features via WordPress actions.

At a high level, the plug-in is composed of five layers:

1. Bootstrap and service registration
2. Asset registration and bundle selection
3. Shortcode renderers and section/control registries
4. Cart, order, and production-asset persistence
5. Admin configuration and product-level metadata

Shortcode Surface Area

The current shortcode files live in includes/shortcode.

Implemented shortcode families in this snapshot:

• apf_common
• apf_3d plus legacy aliases shortcode_3D and shortcode_3d
• apf_texture, apf_3d_texture, apf_stl_texture, apf_stl_mapper
• apf_contour_3d
• apf_planar_3d
• apf_planar_canvas
• apf_photo_print, apf_photo_enhancements
• apf_card_designer
• apf_pdf
• apf_text_layers
• apf_dtf
• apf_embroidery_3d
• apf_metal_art_3d
• apf_rug_tufting
• apf_rfid_magstripes, apf_rfid_magstripe
• apf_sticker_sheets
• apf_window_clings
• apf_translucent_ink_clings, apf_window_clings_translucent_ink

The main bootstrap also references shortcode-contour.php and shortcode-gallery.php, so check file presence and branch state if you are documenting or extending contour/gallery behavior further.

Admin and Product Configuration

Platform admin UI

The platform admin entry point is includes/classes/admin/class-admin.php.

It provides:

• top-level Print Forge admin menu
• settings page
• 3D Models registry page
• Vendor Offers page
• AJAX endpoints:
• apf_admin_get_models
• apf_admin_save_models
• apf_admin_write_surfaces

The model registry persists to apf_models. Settings persist to apf_settings.

Product-level WooCommerce tab

Product integration lives in includes/classes/admin/class-product-model-meta.php.

It adds a WooCommerce product data tab labeled Print Forge.

Stored product meta includes:

• _apf_model_id
• _apf_require_stl
• planar override keys from Planar_Product_Meta

This tab is the main product-level switchboard for:

• choosing a registered APF 3D model
• requiring STL capture on add-to-cart / capture flows
• defining planar-default surfaces and placement values

Surface Builder and templates

Related admin modules include:

• surface builder admin page wiring
• card template admin
• badge template admin
• planar product meta support

These support the authoring side of model surfaces, placements, and template-driven outputs.

AJAX and REST Endpoints

Key AJAX endpoints in the current tree

• apf_add_to_cart
• apf_save_canvas_private
• apf_upload_apa_file
• apf_m3d_capture_save
• apf_make_cutcontour
• apf_cutcontour_export
• apf_cutcontour_save
• apf_gallery_toggle_visibility
• apf_gallery_page
• apf_card_templates_get
• apf_card_templates_save
• badge-builder list/load/export endpoints
• card-designer list/load/export endpoints
• pricing AJAX endpoints from class-ajax-pricing.php

REST endpoints

Inbound media resolution is exposed through REST route registration in the inbound-media classes. Review:

• includes/classes/rest/class-rest-inbound-media.php
• includes/classes/services/class-inbound-media.php

Extension Points and Filters

Notable filters and extension surfaces include:

• apf/debug
• apf_assets_bundles
• apf/pdfjs/src
• apf/pdfjs/ver
• apf/jspdf/src
• apf/jspdf/ver
• apf/critical_style_candidates
• apf/assets/cache_mode
• apf/assets/version
• apf/importmap/enabled
• apf/importmap/three_version
• apf/importmap/imports
• apf/preload_style_handles
• apf_valid_nonce_actions
• apf/credits/config
• apf/ai/gen_credits
• apf/credits/quality_multipliers
• apf/ai/ref_credits
• apf/credits/js_payload

WooCommerce hooks are also central to extension, especially around cart item data, order-line creation, product tabs, and Store API item shaping.

Typical Integration Patterns

Add a new APF-driven product mode

1. Create a shortcode renderer under includes/shortcode.
2. Register or reuse an asset bundle in APF_Assets.
3. Add any product/meta configuration needed in admin classes.
4. If the mode creates previews or generated files, persist them through cart item data and order line items.
5. If the mode generates sensitive artifacts, route them through Private_Files instead of public attachments.

Add a new generated production file type

1. Add client-side generation or upload capture.
2. Submit the file through the M3D or custom AJAX persistence endpoint.
3. Persist attachment IDs or signed URLs into cart item metadata.
4. Copy the metadata into order items at checkout.
5. Wire downstream consumers such as PO generators, fulfillment systems, or vendor handoff processes to read the stored meta.

Add a new admin-managed model type

1. Extend apf_models schema handling in the admin class.
2. Surface fields in the model registry UI.
3. Ensure the viewer-side code understands the new model asset references.
4. If needed, update the product meta tab to allow selection or overrides.

Current deployment evidence

Current observed PrintGhost deployment: 0.18.22. The captured plugin archive print-forge-0.18.22.tar.gz has SHA-256 663a1ebfba864675c0790f7f24ecaddfdfbf5e02c68bafd4ee52876659bfb281, and the deployed main plugin file has SHA-256 f96a476104440a4476fce644d138e65cd116400d5d4a913653d42f63704052bd. The GitHub release reference is v0.18.22 at commit 09bddc158a25f978ee8f3c52a7cd749f47f7a0c3. The normalized deployed file inventory is compatible with the GitHub v0.18.22 release inventory after excluding repository-only CI, build, test, and vendor metadata. For the current v0.18.22 deployment, all 183 shared non-vendor, non-backup files match GitHub v0.18.22 after line-ending normalization; 123 raw differences are line-ending drift, and eight repository-only files are CI, build, lockfile, test, or release metadata. The implementation excerpts on this page are grounded in the authoritative v0.18.22 source reference. The implementation excerpts are anchored to the authoritative v0.18.22 source reference.

Implementation Notes From Current v0.18.22 Source

• The authoritative source reference is GitHub v0.18.22 at commit 09bddc158a25f978ee8f3c52a7cd749f47f7a0c3.
• The bootstrap athenian-print-forge.php defines APF_VER as 0.18.22, requires PHP 8.0+, and enables the modular APF_LEAN_SHELL path.
• WooCommerce cart and quantity integration is centered in includes/classes/class-cart.php (Cart_Handler and filter_vendor_offer_min_qty) and includes/sections/product.php (the #apf-qty input and apt/product_min_qty boundary).
• Pricing behavior is implemented across includes/classes/ajax/class-ajax-pricing.php and assets/js/utilities/pricing.js, including apf_tpt_shortcode, apf_role_discount, vendor/native offer eligibility, and syncQtyFloor.
• Private production artifacts and signed delivery are handled by includes/classes/services/class-private-files.php; nonce and route authorization are centralized in includes/classes/services/class-security.php.
• The current source/release inventory is separate from the deployed runtime scope. See the deployment evidence below for the normalized 183-file parity result and the eight repository-only artifacts.

The current v0.18.22 source identity is authoritative for these three product-linked pages. This documentation still does not claim a live design session, generated artwork, vendor dispatch, shipment, or physical-product fulfillment.