Rug Artisan — Project Overview & System Flow

Purpose: Complete walkthrough of how the Rug Artisan platform works — from design upload to a customer-ready product listing.

What Is This Platform?

Rug Artisan is a custom rug design and product visualisation tool. It allows:

Customers to browse rugs, customise colors, choose materials/sizes, and see realistic product images before ordering.
Admins to upload rug designs, configure product variants, and auto-generate photo-realistic product images using advanced image processing — without needing a photographer or manual Photoshop work.

The system automatically takes a flat SVG design file and produces hundreds of product images showing the rug in different rooms, at different angles, in different weaving textures — all without human effort after the initial upload.

System Overview

[Diagram]

Technology Stack

Layer	Technology
Backend Framework	CakePHP 3.x (PHP)
Database	MySQL
Image Processing	ImageMagick (PHP Imagick extension)
SVG Rendering	Inkscape (command-line)
Frontend	Bootstrap 5 + jQuery
Color Extraction	League\ColorExtractor library
Server	Linux (Apache/Nginx)

System Users

Role	Access	Description
Admin	`/administrator/*`	Full access — uploads designs, manages products, triggers image generation
Vendor	`/administrator/vendors/*`	Vendor-level access to assigned designs
Customer	Public routes	Browses products, customises colors, gets price quotes

Part 1: The Admin Journey (How a Product Gets Created)

Admin Pipeline — Full Flow

[Diagram]

Step 1 — Admin Uploads a Design

The admin logs into the dashboard at /administrator and goes to Designs → Add New Design.

They fill in:

Design Title (e.g. "Floral Garden")
Category (selected from database — e.g. Traditional, Modern)
Weaving Types (e.g. Hand-Tufted, Hand-Knotted, Flatweave)
Shapes (e.g. Rectangle, Round, Oval, Runner)
Complexity (Low / Medium / High — affects delivery time)
Tags (for search/filtering)
SVG Image file(s) — one per shape

The SVG file is the core design — it contains all the colors and patterns of the rug.

What happens behind the scenes:

SVG file uploaded
    → Saved to /webroot/media/svg_files/[design_name]/
    → System extracts all colors from the SVG file
    → Color weights (% area each color occupies) are calculated using Inkscape
    → Design record saved to database with status = 0 (pending)

Step 2 — Generate Color Masks (status 0 → 2)

The admin clicks "Generate Masks" on the design.

The system separates the SVG into individual color layers (masks). Each color region of the rug gets its own PNG mask file.

SVG design (e.g. 5 colors)
    → Color mask 1: Red regions only   → /webroot/media/color-masks/...
    → Color mask 2: Blue regions only  → /webroot/media/color-masks/...
    → Color mask 3: Cream regions only → /webroot/media/color-masks/...
    → ... and so on

These masks are used later to apply weaving textures to individual color zones.

Design status updated → 2 (ready for product generation)

Step 3 — Generate Products (status 2 → 4)

The admin clicks "Generate Products". This is where the system creates all product variants automatically.

For every design, the system generates a product record for every valid combination of:

Dimension	Options
Weaving Type	Hand-Tufted, Hand-Knotted, Flatweave, Outdoor, Handwoven
Material	Pure Wool, Bamboo Silk, Tibetan Wool, New Zealand Wool, Recycled Yarn, Tencel Silk
Pile Height	12–14mm / 14–18mm / 18–22mm (varies by weaving type)
Shape	Rectangle, Square, Round, Oval, Runner, Hexagon, Half-Moon, Diamond, Capsule, Splash, Drop, Figure-8, Ogee, Oblong, Arch

Example: A single design with 3 shapes × 5 weaving types × 3 materials × 2 pile heights = 90 product variants created automatically.

Each product gets:

A unique SKU (e.g. HT-RE-PW-142 = Hand-Tufted, Rectangle, Pure Wool, Design #142)
A URL key for the product page
Pre-calculated prices for all 5 currencies (USD, GBP, EUR, AUD, AED) in both ft² and m²
Color weight data (used for dynamic pricing)

Design status updated → 4 (ready for image generation)

Step 4 — Generate Product Images (status 4 → 6)

The admin clicks "Generate Product Images". This is the most computationally intensive step.

For each product variant, the system renders 4–5 view angles (e.g. top-down, room view left, room view right, lifestyle shot) at both desktop and mobile resolutions.

Image Rendering Pipeline:

[Diagram]

How one product image is rendered:

1. Load the base SVG design file

2. Apply color replacements (Imagick)
   → Each hex color in the SVG replaced with the correct RA color code

3. Convert SVG → PNG (Inkscape CLI)
   → High-resolution flat design image

4. Load weaving texture mask for this shape + weaving type
   → e.g. /webroot/media/weaving-type-masks/handtufted/rectangle/view-rectangle_0.png

5. Composite weaving texture over the design (ImageMagick)
   → Gives the "woven" appearance with pile and texture

6. Apply material-specific filter
   → Silk/Bamboo Silk: adds sheen/highlight effect
   → Loop pile: adds loop texture overlay
   → High pile: adds carving shadow effect

7. Perspective distortion (ImageMagick)
   → Transforms flat image into 3D room-scene perspective

8. Overlay background room image
   → e.g. full-view-rectangle_0.jpg (a pre-prepared room background)

9. Resize for desktop (full size) and mobile (optimised)

10. Save final JPG → /webroot/media/product_images/[design]/[SKU]/
    e.g. floral_garden_handtufted_pure_wool_rectangle_0.jpg

11. Save thumbnail for grid/listing view

12. Save image paths to product_media table in database

Design status updated → 6 (complete)

Step 5 — Color Suggestions (status 6 → done)

After images are generated, the system generates color variation suggestions for each design. These are alternative color combinations that customers can browse as "inspiration" swatches.

Take original design colors
    → Generate N alternative color sets (from the RA color library)
    → Render a thumbnail image for each color combination
    → Save to /webroot/media/suggestions/[SKU]/
    → Store color mappings in design_suggestions table

Part 2: The Customer Journey (How a Customer Uses the Tool)

Customer Journey — Full Flow

[Diagram]

Step 1 — Browse Products

Customers visit the public site and can filter products by:

Category (Traditional, Modern, etc.)
Color family (filtered via product_colors join)

Products are displayed as image cards showing the default variant (rectangle, the most common shape).

Step 2 — Customise Their Rug

When a customer opens a product, they see a live design customizer:

Change colors — Each color region of the rug can be changed independently. The customer picks from the Rug Artisan color library (coded as RA-BT01, RA-BT02, etc.)
Change shape — Switch between rectangle, round, oval, etc.
Change material — Pure Wool, Bamboo Silk, etc.
Change pile height — Affects texture depth and price
Change size — Enter custom width × length in feet or cm

The live preview updates in real time as they make selections. The system re-renders the product image using getUpdatedDesign().

Step 3 — Get a Price

After configuration, the system calls calculatePrice() which:

Looks up the price per sq ft/m² for the selected weaving + material + pile height from price_calculation_master
Multiplies by the color area weight (different materials cost differently if the rug uses multiple material colors)
Multiplies by the rug area (width × height)
Adds 10% premium if high-pile carving is selected
Returns the final price in the customer's selected currency

Step 4 — SVG Color Editor (Standalone Tool)

There is also a public SVG upload tool at /home/edit-svg where anyone can:

Upload their own SVG or PNG file
See all colors detected in the file
Click any color and replace it with another
Download the modified file

This is a separate utility tool independent of the main product catalog.

Part 3: Admin Dashboard Summary

The admin panel at /administrator has these main sections:

Section	What It Does
Dashboard	Overview and quick stats
Designs	Upload designs, manage SVGs, trigger generation pipeline
Products	View all generated products, filter by weaving/shape/material, refresh images
Vendors	Manage vendor accounts and their assigned designs

Data Architecture (Simplified)

[Diagram]

Key Numbers

Item	Detail
Weaving types	5 (Hand-Tufted, Hand-Knotted, Flatweave, Outdoor, Handwoven)
Shapes	15 (Rectangle, Square, Round, Oval, Runner, Hexagon, Half-Moon, Diamond, Capsule, Splash, Drop, Figure-8, Ogee, Oblong, Arch)
Materials	Up to 7 per weaving type
Currencies	5 (USD, GBP, EUR, AUD, AED)
Image views per product	4–5 angles (desktop + mobile versions each)
Color library	200+ named RA colors across families
Max products per design	~90–100 variants auto-generated

Image Storage Structure

/webroot/media/
├── svg_files/[design_name]/          Source SVG design files
├── product_images/[design]/[SKU]/    Generated product images (JPG)
│   └── mobile/[design]/[SKU]/        Mobile-optimised versions
├── suggestions/[SKU]/                Color suggestion thumbnails
├── weaving-type-masks/               Room scene backgrounds + weave texture overlays
│   ├── handtufted/[shape]/
│   ├── handknotted/[shape]/
│   ├── flatweave/[shape]/
│   └── handwoven/[shape]/
├── silk-masks/                       Silk sheen overlay textures
├── loop-masks/                       Loop pile textures
├── color-masks/                      Pre-separated color region masks
├── thumbnail-masks/                  Thumbnail background templates
└── temp_images/                      Temporary Inkscape conversion files

Design Pipeline Status Reference

[Diagram]

Status Code	Meaning
`0`	Design just uploaded — mask generation pending
`2`	Masks generated — ready to generate products
`3`	Product generation in progress
`4`	Products created — ready to generate images
`5`	Image generation in progress
`6`	Image generation done — suggestions pending
`done`	Fully complete and live

Delivery Time Logic

Delivery weeks are calculated automatically based on weaving type and design complexity:

Weaving Type	Low Complexity	Normal	High Complexity
Hand-Tufted	2 weeks	3 weeks	4 weeks
Hand-Knotted	5 weeks	6 weeks	7 weeks
Flatweave	5 weeks	5 weeks	5 weeks
Handwoven	5 weeks	—	5 weeks

Size adjustments apply: large rugs (>20 ft) add 1–2 extra weeks. High-pile carving adds 1 extra week.

Summary

The Rug Artisan platform automates what would traditionally require:

A professional photographer for every rug variant
Manual Photoshop compositing for every room view
Manual pricing spreadsheets for every size/material combination

Instead, the system takes one SVG design file and automatically produces hundreds of photo-realistic product images across all weaving types, materials, shapes, and room views — fully priced and ready to display to customers — at the click of a button.