CGW-Quote-Builder/information/CANVAS_API_QUICKSTART.md

Quick Start: Canvas API Hierarchical Image System

What Is This?

The Canvas API lets you share images across multiple products with automatic fallback. Instead of duplicating the same plants.png file in every product folder, you can have ONE shared file that all products use.

5-Minute Setup

Step 1: Organize Your Images

Create this structure:

app/static/images/
└── doors/
    └── storm/
        ├── 404/
        │   └── door-white.png    # Product-specific
        ├── 505/
        │   └── door-black.png    # Product-specific
        └── layers/
            ├── base.jpg          # Shared by all storm doors
            ├── hardware.png      # Shared by all storm doors
            └── foreground.png    # Shared by all storm doors

Step 2: Enable Canvas API

Edit products.json:

{
  "productCode": "404",
  "description": "#404 FALCON STORM WINDOWS",
  "colors": ["White", "Black"],
  "imageConfig": {
    "useCanvasAPI": true
  }
}

Step 3: Test

1. Start your Flask server
2. Visit: http://localhost:8080/api/canvas/test
3. Should see: {"status": "ok"}
4. Test specific image: http://localhost:8080/api/canvas/404/base
5. Open product page - images should load automatically!

How It Works

When you request /api/canvas/404/door?color=white, the system searches:

1. /images/doors/storm/404/door-white.png ← Checks here first
2. /images/doors/storm/404/door.png
3. /images/doors/storm/layers/door-white.png
4. /images/doors/storm/layers/door.png ← Uses this if 404-specific doesn't exist
5. /images/doors/layers/door.png
6. /images/layers/door.png

Directory Level Guide

Level	Path	Use For	Example
Product	/images/doors/storm/404/	Unique to this product	Custom door colors, unique base
Subtype	/images/doors/storm/layers/	Shared across storm doors	Common hardware, shared plants
Type	/images/doors/layers/	Shared across all doors	Generic handles, railings
Global	/images/layers/	Shared across everything	Default fallback images

Common Scenarios

Scenario 1: All Products Share Plants

Put foreground.png here:

/images/doors/storm/layers/foreground.png

Both product 404 and 505 will use this same file automatically!

Scenario 2: Product 404 Needs Custom Plants

Add product-specific version:

/images/doors/storm/404/foreground.png     ← Product 404 uses this
/images/doors/storm/layers/foreground.png  ← Product 505 uses this

Scenario 3: Same Hardware for All Doors

Put at type level:

/images/doors/layers/hardware.png

Every door product (storm, entry, patio) uses the same hardware!

Real-World Example

Before (Static Layered System)

/images/products/404/
    base.jpg          (800KB)
    door-white.png    (200KB)
    hardware.png      (100KB) ← Duplicate
    plants.png        (150KB) ← Duplicate

/images/products/505/
    base.jpg          (800KB)
    door-black.png    (200KB)
    hardware.png      (100KB) ← Duplicate!
    plants.png        (150KB) ← Duplicate!

Total: 2.5MB

After (Canvas API)

/images/doors/storm/404/
    base.jpg          (800KB)
    door-white.png    (200KB)

/images/doors/storm/505/
    base.jpg          (800KB)
    door-black.png    (200KB)

/images/doors/storm/layers/
    hardware.png      (100KB) ← Shared!
    plants.png        (150KB) ← Shared!

Total: 2.25MB (saved 250KB)

With 10 products sharing the same hardware/plants, you'd save ~2MB!

Quick Reference

Enable for a Product

{
  "productCode": "404",
  "imageConfig": {
    "useCanvasAPI": true
  }
}

API Endpoints

/api/canvas/<product_code>/<layer>?color=<color>
/api/canvas/<product_code>/info
/api/canvas/test

Valid Layers

• base - Background/house
• door - Door/window panel
• hardware - Handles/locks
• overlay - Glass views
• foreground - Plants/decorations

Directory Pattern

/images/<type>/<subtype>/<product_code>/<layer>-<color>.<ext>
/images/<type>/<subtype>/layers/<layer>.<ext>
/images/<type>/layers/<layer>.<ext>
/images/layers/<layer>.<ext>

Troubleshooting

Images not loading?

1. Check Flask logs: [INFO] Found image: /path/to/file
2. Visit: /api/canvas/YOUR-PRODUCT/info
3. Verify "useCanvasAPI": true in products.json
4. Check baseType/subType match directory structure

Wrong image showing?

• More specific paths override generic ones
• Product-specific overrides subtype
• Subtype overrides type
• Type overrides global

404 error?

• File doesn't exist at any fallback level
• Check file naming (lowercase for colors)
• Verify directory structure matches type/subtype

Next Steps

1. ✅ Read the full Canvas API Guide for advanced features
2. ✅ Review example JSON configurations
3. ✅ Check the fallback system documentation

Benefits

✅ Eliminate duplication - Share common files across products
✅ Easier updates - Change one file, affects all products
✅ Smaller total size - Less storage and bandwidth
✅ Smart fallbacks - Products automatically inherit shared elements
✅ Flexible organization - Add product-specific overrides anytime

That's it! Start organizing your images by type/subtype and watch the magic happen. 🎨