Initial

2026-04-11 00:04:09 -05:00
commit 7a2fffd62e
110 changed files with 51809 additions and 0 deletions
@@ -0,0 +1,239 @@
+# 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)