CGW-Quote-Builder/planning/ENCODING_SYSTEM.md

Product Encoding System

Overview

This document describes the hex-based encoding system for creating stable, bookmarkable URLs for product configurations. The system uses bit-packing to create compact strings that encode product type, color, material, and hardware options.

Design Goals

1. Stable URLs: Old bookmarks continue to work even as new options are added
2. Compact: Keep URLs under 32-64 characters
3. Extensible: Reserve space for future expansion
4. Reversible: Each encoded string can be uniquely decoded back to its components
5. Version-aware: Support future format changes without breaking old URLs

Encoding Format

Format: v-T-C-M-HHHH-HHHH-HHHH
        │ │ │ │ │    │    └── Hardware 3 (optional)
        │ │ │ │ │    └─────── Hardware 2 (optional)
        │ │ │ │ └──────────── Hardware 1
        │ │ │ └────────────── Material (1 hex char, 0-F)
        │ │ └──────────────── Color (1 hex char, 0-F)
        │ └────────────────── Type (1 hex char, 0-F)
        └──────────────────── Version (1 hex char, 0-F)

Example: "0-1-4-1-0D94"
- Version: 0 (using 5-bit encoding per field)
- Type: 1 (Patio Door)
- Color: 4 (White)
- Material: 1 (Aluminum)
- Hardware 1: 0D94 (Lever, Standard, Brass)

Max Length: ~24 characters (with 3 hardware items)

Version 0 Encoding (Current)

Main Product Attributes (Single Hex Character Each)

Each main attribute uses a single hex character (0-F = 0-15):

Type Values (1 hex char)

1  = Patio Door
2  = Reserved
3  = Storm Door
4  = Reserved
5  = Storm Window
6  = Reserved
7  = Primary Window
8-F = Reserved (8 slots for future door/window types)

Color Values (1 hex char)

1 = Black
2 = Bronze
3 = Sandstone
4 = White
5 = Tan
6 = Mill
7-F = Reserved (9 slots for future colors)

Material Values (1 hex char)

1 = Aluminum
2 = Vinyl
3-F = Reserved (13 slots for future materials)

Hardware Encoding (4 Hex Characters = FFFF)

Each hardware item uses 4 hex characters (16 bits) split into fields using 5 bits per field:

16 bits total:
- Bits 10-14: Type (5 bits, 0-31 values)
- Bits 5-9:   Style (5 bits, 0-31 values)
- Bits 0-4:   Color (5 bits, 0-31 values)
- Bit 15:     Reserved (1 bit)

Hardware Type Values (5 bits = 0-31)

0  = None/Not Set
1  = Lever
2  = Pull
3  = Pull Handle
4  = Deadbolt
5  = Hinge
6-31 = Reserved (26 slots)

Hardware Style Values (5 bits = 0-31)

0  = None/Not Set
1  = Standard
2  = Push
3  = Alternative
4  = Contemporary
5  = Traditional
6-31 = Reserved (26 slots)

Hardware Color Values (5 bits = 0-31)

0  = None/Not Set
1  = Brass
2  = White
3  = Black
4  = Satin
5  = Nickel
6  = Bronze
7-31 = Reserved (25 slots)

Bit Math Examples

Encoding Hardware

Example: Lever, Standard, Brass
- Type: 1 (Lever)
- Style: 1 (Standard)
- Color: 1 (Brass)

Binary calculation:
Type (1)  = 00001 (bits 10-14)
Style (1) = 00001 (bits 5-9)
Color (1) = 00001 (bits 0-4)

Combined: 0000010000100001 = 0x0421
Hex: "0421"

Example: Pull Handle, Alternative, Satin
- Type: 3 (Pull Handle)
- Style: 3 (Alternative)
- Color: 4 (Satin)

Binary calculation:
Type (3)  = 00011 (bits 10-14)
Style (3) = 00011 (bits 5-9)
Color (4) = 00100 (bits 0-4)

Combined: 0000110001100100 = 0x0C64
Hex: "0C64"

Decoding Hardware

Given hex: "0D94"
Binary: 0000110110010100

Extract fields:
Type  = bits 10-14 = 00011 = 3 (Pull Handle)
Style = bits 5-9   = 01100 = 12
Color = bits 0-4   = 10100 = 20

URL Examples

Simple Products (No Hardware)

"0-1-4-1" = Patio Door, White, Aluminum
"0-3-4-1" = Storm Door, White, Aluminum
"0-7-1-1" = Primary Window, Black, Aluminum
"0-5-2-2" = Storm Window, Bronze, Vinyl

Products with Hardware

"0-3-4-1-0421" = Storm Door, White, Aluminum, Lever-Standard-Brass
"0-3-1-1-0421-0C64" = Storm Door, Black, Aluminum, 
                       Hardware1: Lever-Standard-Brass,
                       Hardware2: Pull Handle-Alternative-Satin

Expansion Strategy

Adding New Options (Compatible)

When adding new options within existing capacity (0-15 for main attributes, 0-31 for hardware fields):

Old system: Color 1-6 defined, 7-15 reserved
New system: Add Color 7 = Charcoal

Old URLs still work: "0-1-4-1" still means Patio Door, White, Aluminum
New URLs use new values: "0-1-7-1" means Patio Door, Charcoal, Aluminum

Version 1 (Future Expansion)

If we exceed 16 main attribute values or 32 hardware field values:

Version 1: Use 6 bits per hardware field (64 values each)
Format: "1-TT-CC-MM-HHHHH-HHHHH"

Changes:
- Main attributes expand to 2 hex chars each (256 values)
- Hardware expands to 5 hex chars each (18 bits = 6 bits per field)

Compatibility Rules

1. Never reuse reserved values until a new version is released
2. Never change existing value meanings (e.g., don't make "1" mean something else)
3. Always decode based on version character
4. Maintain lookup tables for each version

Implementation Notes

• Use bit-shifting operators (<<, >>) for performance
• Use bitwise AND (&) with masks to extract fields
• Pad hex strings with leading zeros to fixed width
• Validate decoded values against valid ranges
• Return error for unknown version codes

Benefits

✅ Stable: Values 0-15 remain the same even if we expand to 0-31
✅ Compact: 13-24 characters for most products
✅ Readable: Hex is human-debuggable
✅ Efficient: Single parse operation, no string splitting
✅ Extensible: Version prefix allows future format changes
✅ Reliable: Bit operations are deterministic and reversible

---

Last Updated: March 26, 2026
Current Version: 0 (5-bit hardware encoding)