Athenian Print Forge

Developer starting point

This page documents the authoritative Print Forge v0.18.22 source and the matching representative PrintGhost deployment. The authoritative v0.18.22 source and the representative PrintGhost runtime match across 183 shared non-vendor, non-backup files after line-ending normalization. The 123 raw differences are line-ending representation drift, and eight source-only files are repository CI, build, lockfile, test, and release metadata. It does not claim a live design session, generated artwork, vendor dispatch, shipment, or physical-product fulfillment.

Customer-Facing Workflow

1. A shopper lands on a WooCommerce product page or embedded APF build surface.
2. The page loads a specific Print Forge shortcode for the product type, such as a 3D mockup, planar product, contour workflow, badge builder, photo print tool, or label generator.
3. The shopper selects a product, variation, quantity, styling options, uploaded media, generated image, text layers, surface placement, or production-related options.
4. The front end can render previews using shared controls, media picker components, PDF tooling, Three.js modules, canvas capture, and product-specific viewers.
5. Production files or preview captures are saved through AJAX endpoints, either as Media Library attachments or private signed files.
6. The configured product is added to WooCommerce cart with APF metadata attached.
7. At checkout, APF cart metadata is copied into the WooCommerce order item so staff, vendors, PO systems, or fulfillment workflows can access the production context.

Admin Workflow

Print Forge Admin Menu

The plugin registers a top-level Print Forge admin area with pages for:

• Overview / Settings
• Saved Badges
• Badge Templates
• 3D Models
• Vendor Offers
• Asset Purge

The main admin capability is manage_options.

Settings

Plugin settings are stored under apf_settings. Key settings and defaults include:

• admin debug flag
• default model selection
• vendor default margin percentage
• vendor minimum margin percentage
• CutContour download credit costs for PDF, SVG, and PNG
• notes
• planar defaults

3D Model Registry

The model registry is stored in the apf_models option and supports model IDs, names, slugs, GLB/GLTF references, surface data, and model-level settings. Product pages can select a default model globally or override the model per product.

WooCommerce Product Data Tab

The plugin adds a Print Forge product data tab to WooCommerce products. Product-level metadata includes:

• _apf_model_id - selected 3D model identifier.
• _apf_require_stl - whether STL/generation capture should be required.
• _apf_planar_enabled - whether planar configuration is enabled.
• _apf_planar_cfg - JSON planar configuration for surfaces, shape, placement, scaling, rotation, background, transparency, and related rendering defaults.
• _apf_badge_template_id - product-linked badge template reference.

Badge Templates and Saved Badge Designs

The plugin registers private admin-facing CPTs for reusable badge workflows:

• apf_badge_template for administrator-defined badge templates.
• apf_badge_user_tpl for user-saved badge designs.

Badge templates store JSON under _apf_badge_template_json. User-saved templates can store template JSON, preview attachment IDs, source template IDs, and product IDs.

Shortcode Surface Area

| Shortcode | Purpose | | --- | --- | | [apf_common] | Shared APF shell for product/variation controls, pricing, media, styling, and reusable sections. | | [apf_3d] / [shortcode_3D] / [shortcode_3d] | Legacy-compatible 3D product experience. | | [apf_texture], [apf_3d_texture], [apf_stl_texture], [apf_stl_mapper] | STL/texture mapping and 3D texture workflows. | | [apf_planar_3d] | Planar 3D product rendering for flat/surface-based products. | | [apf_planar_canvas] | Planar canvas output and compatibility workflow. | | [apf_contour] | 2D contour/cut workflow. | | [apf_contour_3d] | 3D contour workflow and viewer stack. | | [apf_dtf] | DTF-oriented product builder/viewer. | | [apf_embroidery_3d] | Embroidery-oriented 3D customization workflow. | | [apf_metal_art_3d] | Metal art/fabrication-style 3D workflow. | | [apf_rug_tufting] | Rug tufting visualization/customization workflow. | | [apf_neon_light] / [apf_neon_sign] | Neon-style sign builder and preview workflow. | | [apf_window_clings], [apf_micro_perf_clings], [apf_window_clings_micro_perf] | Window cling and micro-perf product workflows. | | [apf_translucent_window_clings], [apf_translucent_ink_clings], [apf_window_clings_translucent_ink] | Translucent ink/window cling workflows. | | [apf_photo_print], [apf_photo_enhancements] | Photo print and enhancement workflow. | | [apf_gallery] / [apf-gallery] | APF media/gallery browsing and selection. | | [apf_name_insights_3d], [apf_name_story_3d] | Name/story generation and 3D-contextual display. | | [apf_pdf] | PDF viewer/preview workflow. | | [apf_text_layers] | Text-layer design workflow with font picker and capture hooks. | | [apf_badge_builder] | Badge design workflow with templates, fields, QR/barcode support, and user-saved designs. | | [apf_variable_labels] | Variable-label workflow with CSV-style row data and PDF output persistence. | | [apf_rfid_magstripes], [apf_rfid_magstripe] | RFID/magstripe product configuration and order metadata capture. |

Technical Architecture

1. Bootstrap Layer

The main plugin file is athenian-print-forge.php. It defines core constants, registers activation/deactivation hooks, loads localization, sets up a small classmap autoloader, conditionally loads function modules, and wires runtime boot hooks.

Key constants include:

• APF_FILE
• APF_PATH
• APF_URL
• APF_BASENAME
• APF_VER
• APF_MIN_PHP
• APF_DEBUG
• APF_DEV_NOCACHE
• APF_LEAN_SHELL

The APF_LEAN_SHELL flag is used to keep newer modular renderers separated from older monolithic rendering behavior.

2. Asset Layer

The APF_Assets class registers all major frontend and admin CSS/JS handles and exposes bundle helpers such as:

• use_common()
• use_contour()
• use_gallery()
• use_media()
• use_badge_builder()
• use_variable_labels()
• use_texture_3d()
• use_planar_3d()
• use_pdf_viewer()
• use_text_layers()
• use_embroidery()
• use_rug_tufting()
• use_neon_light()
• use_photo_enhance()
• use_rfid_magstripes()
• use_dtf()
• use_window_clings()
• use_translucent_window_clings()
• use_m3d_modal()
• use_admin_surface_builder()

The bundle map is filterable through apf_assets_bundles, and the plugin includes import-map support for module-based Three.js workflows.

3. Control and Section Layer

The plugin uses a control registry plus auto-discovered section files under includes/sections. These sections represent reusable UI blocks such as product controls, uploads, canvas tools, gallery/media controls, PDF tools, tier tables, styling panels, badge builder, variable labels, RFID/magstripes, neon, contour, mockup/3D controls, downloads, and product variations.

This architecture lets specialized shortcode renderers compose shared controls without duplicating every UI component.

4. Cart and Order Layer

The APF\Cart\Cart_Handler class owns much of the WooCommerce integration:

• apf_add_to_cart AJAX flow.
• APF metadata collection from native POST and Store API requests.
• Cart-session restoration.
• Cart-row display metadata.
• Custom thumbnails and preview handling.
• apf_save_canvas_private private-canvas save endpoint.
• apf_upload_apa_file native file upload endpoint.
• M3D and RFID metadata order-line persistence.
• Variable-label order-line persistence.
• STL-required validation logic.

Separate capture modules support:

• APF\M3D\Capture_Cart for preview PNGs and generated 3D/production files.
• APF\CutContour\Capture_Cart for CutContour PDF IDs/URLs and order item metadata.

5. Media and File Layer

The plugin includes several media-related services:

• APF\Services\Media - attachment metadata, gallery pagination, AI image save, media picker filtering, attachment cache handling, and media response shaping.
• APF\Services\Media_AI - AI/generated image save flow and metadata capture.
• APF\Services\Media_Gallery - AJAX-backed gallery pagination.
• APF\Services\Media_Visibility - canvas/internal capture visibility handling and cart/order bridge logic.
• APF\Services\Private_Files - private artifact storage, signed URL generation, streamable /apf-file endpoint, Range request support, and daily cleanup cron.
• APF\Services\Asset_Manager - attachment association with products, orders, order items, lifecycle state, and production context.

6. Security Layer

AthenianPrintForge\Services\Security centralizes nonce issuance and verification. It can read nonce values from form fields, JSON request bodies, and headers. The plugin uses route-specific action buckets for flows such as cart, AI, pricing, CutContour, generic APF actions, and REST-style requests.

7. Credits Layer

AthenianPrintForge\Services\Credits provides configurable APF credit pricing and balance/cost endpoints. It prefers CPM_Credits if available and falls back to credit balance user meta where appropriate. Credit pricing supports:

• generation size cost maps
• quality multipliers
• reference-image surcharges
• flat image/output charges
• filterable configuration through apf/credits/config
• JavaScript payload localization through APF asset bundles

8. Pricing Layer

AthenianPrintForge\Ajax\Ajax_Pricing exposes:

• apf_tpt_shortcode for AJAX-rendering tiered pricing table output.
• apf_role_discount for role-discount lookup.

The role-discount logic can work with Athenian\RoleManagement\Role_Discounts when present and includes helpers to resolve parent product IDs from variations.

AJAX Endpoints

| Endpoint / Action | Purpose | | --- | --- | | apf_add_to_cart | Add configured APF product data into WooCommerce cart. | | apf_save_canvas_private | Save customer-specific canvas artifacts into private storage. | | apf_upload_apa_file | Upload APF/APA-style files from the frontend. | | apf_m3d_capture_save | Save M3D preview captures and generated production files. | | apf_make_cutcontour / apf_cutcontour_export | Generate or export CutContour production outputs. | | apf_cutcontour_download_charge | Charge credits for CutContour download actions. | | apf_cutcontour_save | Save CutContour artifact data. | | apf_gallery_page | Paginated APF media/gallery loading. | | apf_gallery_toggle_visibility | Admin/user visibility toggle for gallery media. | | apf_save_ai_image | Save AI-generated or remote image content to the Media Library. | | apf_credits_balance_v2 | Return APF credit balance. | | apf_credits_cost_v2 | Return APF credit cost estimates. | | apf_tpt_shortcode | Render tiered-pricing shortcode output through AJAX. | | apf_role_discount | Return role-discount context for current product/user. | | apf_admin_get_models | Admin model-registry read endpoint. | | apf_admin_save_models | Admin model-registry save endpoint. | | apf_admin_write_surfaces | Write surface JSON for model/surface-builder workflows. | | Badge builder endpoints | Template listing, loading, saving, exporting, and user-template management. | | Variable-label endpoints | Label payload/PDF capture and cart/order persistence support. |

Data Model and Stored Values

WordPress Options

| Option | Purpose | | --- | --- | | apf_settings | Main plugin settings. | | apf_models | Registered APF 3D/product models. | | apf_credits_config | Credit pricing configuration. | | apf_asset_cache_mode | Asset cache behavior. | | apf_default_pdf_url | Default PDF URL for PDF viewer-style workflows. | | apf_default_blueprint_pdf_url | Default blueprint PDF reference. | | apf_default_photo_print_product_id | Default product mapping for photo-print flows. | | apf_needs_flush | Activation-time rewrite flush marker. |

Product Metadata

| Meta Key | Purpose | | --- | --- | | _apf_model_id | Product-selected APF model. | | _apf_require_stl | STL/capture requirement flag. | | _apf_planar_enabled | Enables planar product configuration. | | _apf_planar_cfg | JSON planar product configuration. | | _apf_badge_template_id | Badge template assigned to a product. |

Attachment Metadata

| Meta Key | Purpose | | --- | --- | | _apf_asset_kind | Classifies APF-generated or APF-managed media. | | _apf_asset_lifecycle | Lifecycle state for managed assets. | | _apf_asset_order_id | Associated order. | | _apf_asset_order_item_id | Associated order item. | | _apf_asset_product_id | Associated product. | | _apf_asset_variation_id | Associated variation. | | _apf_asset_pipeline | AI/production pipeline provenance. | | _apf_asset_variant | Variant/type marker. | | _apf_media_role | Gallery/media role classification. | | _apf_gallery_exclude | Gallery exclusion flag. | | _apf_visibility | Visibility state. |

Order Item Metadata

| Meta Key | Purpose | | --- | --- | | _apf_m3d | Main M3D/capture bundle JSON. | | _apf_m3d_previews | Preview URL list. | | _apf_m3d_preview_ids | Preview attachment ID list. | | _apf_m3d_generated_files | Generated production-file metadata. | | _apf_cutcontour_pdf_url | CutContour PDF URL. | | _apf_cutcontour_pdf_id | CutContour PDF attachment ID. | | _apf_cutcontour | CutContour bundle JSON. | | apf_rfid_magstripe | RFID/magstripe configuration payload. | | apf_variable_labels | Variable-label payload. | | _apf_variable_labels_row_count | Variable-label row count. | | _apf_variable_labels_pdf_url | Generated label PDF URL. | | _apf_variable_labels_pdf_id | Generated label PDF attachment ID. | | _apf_canvas_meta | Canvas/internal capture metadata. |

Integration Points

WooCommerce

Print Forge integrates with WooCommerce through:

• product data tabs
• product metadata
• cart item data filters
• cart session restoration
• cart item display metadata
• checkout order-line creation hooks
• Store API cart item extension hooks
• product/variation parent resolution
• order admin asset modals
• product-level validation rules

Athenian Platform Core

Platform Core can provide shared taxonomy, service registry, UI conventions, policy/routing patterns, and platform-level schema expectations around vendors, products, creators, and marketplace logic.

Product Add-ons

Product Add-ons can provide richer add-on forms, file fields, design fields, and cart add-on data that complement Print Forge's visual product builders.

Pricing Tiers and Role Discounts

Print Forge's pricing AJAX layer can surface tiered pricing and role-based discount context. This allows configurable products to keep wholesale, reseller, membership, and trade-account pricing behavior without duplicating pricing logic inside every shortcode.

WC Dropship and Vendor Offers

Print Forge is designed to pair with vendor-aware pricing and order-routing workflows. The customization experience can produce the product and asset payload while dropship/vendor modules determine supplier eligibility, PO generation, vendor handoff, fulfillment responsibility, and shipping workflows.

Shipment Manager

Shipment Manager can consume APF order metadata, preview assets, production files, and order-line context as part of packing-station, label, partial-shipment, and fulfillment workflows.

Creator Manager and Affiliate Manager

Media assets and creator-driven design inputs can be associated with order items, while affiliate or creator attribution layers can participate in commission calculations and downstream OwlPay payout flows.

OwlPay

OwlPay can act as the ledger and payout execution layer for creators, affiliates, vendors, and other parties involved in custom-product transactions.

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.

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.