ProjectsParts ServicesMedia
Image Metadata Architecture
Embed product metadata directly into images (XMP) so it's never lost, even when images are shared or found via Google.
Image Metadata Architecture
Overview
Embed product metadata directly into images (XMP) so it's never lost, even when images are shared or found via Google.
Metadata Schema
{
"schemaVersion": "1.0",
"createdAt": "2025-11-25T10:00:00Z",
"updatedAt": "2025-11-25T10:00:00Z",
"company": {
"name": "Clinton Tractor & Implement Co.",
"type": "Authorized Reseller",
"website": "https://clintontractor.com"
},
"legal": {
"copyright": "© 2025 Clinton Tractor & Implement Co. All rights reserved.",
"license": "Licensed for Clinton Tractor e-commerce use only."
},
"product": {
"sku": "CT-NHL-00907566",
"partNumber": "00907566",
"pnNorm": "907566",
"title": "Hydraulic Filter Element",
"manufacturer": {
"name": "New Holland",
"code": "NHL"
},
"categoryName": ["Filters", "Hydraulic Filters"],
"categoryPath": ["Parts - Filters - Hydraulic Filters"],
"equipmentFitment": ["T7.270", "T7.290"],
"status": "active"
},
"image": {
"type": "marketing",
"sortOrder": 1,
"source": "vendor_scraped",
"alt": "Hydraulic Filter Element"
},
"catalog": {
"url": "https://clintontractor.com/parts/ct-nhl-00907566",
"slug": "hydraulic-filter-element-00907566"
},
"embedding": {
"embedded": true,
"embeddedAt": "2025-11-25T10:30:00Z",
"version": "2025.11.25",
"processor": "local-worker-01"
}
}SKU System
Format: CT-VENDOR-PARTNUMBER
| Component | Source | Example |
|---|---|---|
| CT | Constant prefix | CT |
| VENDOR | manufacturer.code | NHL, BNS, GRP |
| PARTNUMBER | partNumber | 00907566 |
Result: CT-NHL-00907566
Storage Architecture
| What | Where | Purpose |
|---|---|---|
| JSON sidecar | GCS next to image | Source of truth |
| XMP metadata | Inside image file | Inseparable from image |
| Copy | MongoDB | Fast queries |
| Copy | Elasticsearch | Full-text search |
Hybrid Processing System
MODE: HYBRID (Local primary, Cloud fallback)
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Task Queue │────►│ Router │────►│ Worker │
│ │ │ │ │ Local/Cloud │
└─────────────┘ └─────────────┘ └─────────────┘
│
┌──────┴──────┐
▼ ▼
[LOCAL] [CLOUD]
Primary Fallback
FREE $0.12/GBCost Summary
Processing 5M images:
| Processing | Cost |
|---|---|
| Cloud Only | ~$590 |
| Local (recommended) | ~$50-100 |
| Savings | $490+ |
File Structure in GCS
gs://crop_parts/nhl/gallery/00907566/
├── 00907566-1.jpg ← Image with XMP embedded
├── 00907566-1.meta.json ← Source of truth
├── 00907566-2.jpg
└── 00907566-2.meta.jsonField Naming Convention
All fields use camelCase (consistent with IndexedPart):
| Field | Style | Example |
|---|---|---|
| partNumber | camelCase | 00907566 |
| pnNorm | camelCase | 907566 |
| equipmentFitment | camelCase | T7.270 |
| categoryName | camelCase | Filters |
| categoryPath | camelCase | Parts - Filters |
Key Fields for AI Recognition
| Field | Value | Purpose |
|---|---|---|
| company.name | Clinton Tractor & Implement Co. | Brand identification |
| product.sku | CT-NHL-00907566 | Unique Clinton Tractor SKU |
| product.partNumber | 00907566 | OEM part number |
| legal.copyright | © 2025 Clinton Tractor... | Legal protection |
| catalog.url | clintontractor.com/... | Direct product link |
Amazon Product Data Enrichment
Comprehensive plan for enriching CROP product data using Amazon's product information.
Image Metadata Architecture — Final Detailed
This document defines the complete architecture for embedding, storing, and managing product image metadata for Clinton Tractor & Implement Co. The system...