Expand Plant Image Coverage via Proxy & Fallback Chain

Status: Draft | Product: Platform — Plant Catalog

Problem

SimplyScapes has 10,000 plants in the database but only 2,000 have transparent cutout images. The Visual Designer requires transparent images to render plants on canvas, so 8,000 plants are invisible to designers — even when they search by name and the plant exists in our library.

This is a discoverability and trust problem. A designer searches for "Acer palmatum 'Bloodgood'" and gets zero results, despite having full botanical data for that plant. They assume SimplyScapes doesn't carry it. Meanwhile, we already have transparent images for 3-4 other Japanese Maple cultivars that would be visually indistinguishable at design scale.

Impact: 80% of the plant library is inaccessible. Designers work around this by uploading custom images or choosing different plants entirely — both of which degrade design accuracy and erode confidence in the platform.

Solution: Multi-Layer Image Resolution Chain

Introduce a fallback chain that resolves a display image for every plant, with clear fidelity indicators so users always know what they're looking at.

Layer 1: Plant's own transparent images       → Direct match (status quo)
Layer 2: Curated proxy plant mapping           → Admin-assigned substitute image
Layer 3: Genus + habit + size auto-match       → Algorithmic best-fit from same genus
Layer 4: SVG silhouette placeholder            → Plant-type outline (tree, shrub, grass, etc.)

Each layer is independent and additive. A plant resolved at Layer 2 still upgrades to Layer 1 when a direct image is added later. The resolution layer is stored as metadata so the UI can communicate fidelity to the user.

User Stories

US-1: Designer finds previously hidden plants As a landscape designer, I want to search for any plant in the library and see it in results, so I can specify the botanically correct plant even if a direct cutout image doesn't exist yet.

US-2: Designer understands image fidelity As a designer, I want to know whether a plant's image is exact, a close substitute, or a placeholder, so I can make informed decisions about visual accuracy in client-facing proposals.

US-3: Designer places proxy-imaged plants on canvas As a designer, I want to drag a proxy-imaged plant onto my design and have it render using the substitute image, so I'm not blocked from specifying the right plant.

US-4: Admin curates proxy mappings As a plant catalog admin, I want to manually assign proxy image sources for high-demand plants, so the most-searched plants get the best visual match.

US-5: Designer generates plant reports with all plants As a designer, I want exported PDFs and plant schedules to include every plant in my design — proxy-imaged or not — with correct botanical data, thumbnails, and retail links.

UX Design

See ux/wireframes.md for detailed interaction flows and wireframes.

Key UX Decisions

1. How proxy plants appear in search results

All 10,000 plants appear in search results. The plant card displays a small indicator badge showing the image source tier:

| Badge | Meaning | Visual Treatment | |-------|---------|-----------------| | (none) | Direct image — exact cutout for this plant | No change from today | | "Similar image" | Proxy or genus-match image from a related plant | Subtle label below thumbnail | | "Silhouette" | SVG placeholder — no photographic image available | Muted card with silhouette |

Users can filter results to show only plants with direct images (power-user toggle, off by default). The default shows all plants.

2. How proxy plants appear on canvas

On the canvas, proxy-imaged plants render identically to direct-imaged plants. The substitute image is visually appropriate (same genus, similar habit and size). There is no badge or overlay on the canvas itself — it would clutter the design.

The distinction is visible in:

• Plant details panel (sidebar): shows "Image: Similar — sourced from [Proxy Plant Name]"
• Plant schedule/roster: includes an "Image source" column in the bill of materials

3. How proxy plants appear in exports & reports

| Export Type | Behavior | |-------------|----------| | PDF design view | Renders proxy image as-is (no badge on design) | | Plant schedule table | Shows plant's own name, botanical data, and retail links. Thumbnail uses proxy image. Optional footnote: "† Representative image" | | Plant detail cards (if included in report) | Full botanical data. Thumbnail with "Representative image" caption | | Shared link / gallery | Renders proxy image. Plant info panel shows source attribution |

4. How it affects the plant detail panel

The existing plant detail panel (right sidebar when a plant is selected) already shows: name, scientific name, images, size, zones, water/sun, bloom, description, retailer links, collections.

Changes:

• Image carousel: Shows proxy images with a "Similar image from [Name]" caption
• New "Image status" line: "Direct image", "Similar image from Acer palmatum 'Sango-kaku'", or "Silhouette only"
• Call to action (admin only): "Upload transparent image" button to promote from proxy to direct

Affected Systems

Visual Designer (designer repo)

• Plant search & filter — Remove the implicit transparent_images_aggregate > 0 filter. Add image-source badge rendering to plant cards.
• Canvas rendering — Resolve image via fallback chain instead of direct FK. No visual change on canvas.
• Plant details panel — Show image source attribution and fidelity indicator.
• Plant schedule / bill of materials — Include proxy-imaged plants. Add representative-image footnote.

PDF Export & Document Generation (designer + web repos)

• Design PDF — No change to canvas rendering. Plant schedule table gains footnote column.
• Plant schedule PDF template — Thumbnail resolution uses fallback chain. "Representative image" notation.
• Shared link viewer — Plant info overlay shows image source.

Plant Catalog Admin (web repo)

• Plant edit page — New "Proxy Image Source" field: searchable plant selector, restricted to plants with transparent images.
• Bulk proxy assignment tool — Admin page that runs the genus + habit + size matching algorithm and presents suggested mappings for review/approval.
• Image coverage dashboard — Summary stats: X plants with direct images, Y with proxy, Z with genus-match, W with silhouette only.

Plant Catalog API (labs + hasura-cicd repos)

• Schema change — New proxy_image_plant_id nullable FK on plant table pointing to another plant's transparent images.
• GraphQL API — New computed field or view: resolved_transparent_image that walks the fallback chain.
• Retailer catalog sync (/api/v1/plantCatalog) — Update PlantRecord interface to include proxy_image_plant_id. Expand candidate matching to include proxy-imaged plants.

Hasura Permissions (hasura-cicd repo)

• Row-level security — proxy_image_plant_id readable by all roles. Writable by admin only.
• Computed field permissions — resolved_transparent_image readable by all roles.

Help Documentation (labs repo)

• search-plants.md — Update to explain that all plants now appear in search.
• explore-plant-library.md — Update plant counts. Explain "Similar image" badge.
• filter-plants.md — Document the "Direct images only" filter toggle.
• New article: understanding-plant-images.md — Explain the image tiers and what "Similar image" means.

AI Embeddings (future, labs repo)

• Plant embedding vectors — When the vector embeddings platform ships, proxy-imaged plants participate in semantic search. Image vectors use the resolved (proxy) image, text vectors use the plant's own metadata.

Implementation Phases

Phase 1: Curated Proxy Mapping

Goal: Admin-driven proxy assignment for the highest-demand plants.

• Add proxy_image_plant_id column to plant table
• Build admin UI: searchable proxy selector on plant edit page
• Build resolved_transparent_image computed field/view
• Update Visual Designer search to show all plants (remove image-existence filter)
• Add "Similar image" badge to plant cards
• Update plant details panel with image source attribution
• Update plant schedule/PDF to handle proxy thumbnails
• Seed initial mappings: script matches on parent_plant_id, comparable_plants jsonb, and exact genus + species

Expected coverage: ~4,000–5,000 plants (from 2,000 direct + 2,000–3,000 proxy-mapped via cultivar families and admin curation)

Phase 2: Genus-Level Auto-Fallback

Goal: Algorithmic fallback for the long tail that doesn't warrant manual curation.

• Build genus + habit + size matching algorithm
• Create plant_image_fallback materialized view (refreshed nightly or on plant save)
• Extend resolved_transparent_image to consult fallback view when no proxy is set
• Add "Auto-matched" variant of "Similar image" badge
• Build admin coverage dashboard

Expected coverage: ~8,000–9,000 plants

Phase 3: AI Background Removal Pipeline

Goal: Generate direct transparent images from existing plant photos.

• Integrate AI background removal (rembg/U2Net or API service)
• Batch process plant_image photos → candidate plant_transparent_image records
• Admin QA review queue: approve/reject generated cutouts
• Approved images promote plant from proxy to direct

Expected coverage: ~9,000–10,000 plants (remaining gaps are plants with no photos at all — these stay on genus fallback or silhouette)

Success Metrics

| Metric | Baseline | Phase 1 Target | Phase 2 Target | Phase 3 Target | |--------|----------|----------------|----------------|----------------| | Plants visible in designer | 2,000 | 5,000 | 9,000 | 9,500+ | | Search-to-place conversion | Baseline TBD | +30% | +50% | +60% | | "Plant not found" support tickets | Baseline TBD | -40% | -70% | -80% | | Custom image uploads (workaround) | Baseline TBD | -20% | -40% | -50% |

Open Questions

1. Should proxy plants be flagged in the shared gallery? If a client sees a design in the public gallery, should "Similar image" plants be distinguishable? Recommendation: no — it clutters the client experience and the visual difference is negligible.
2. Licensing implications: Transparent images have attribution, license, and license_url fields. When an image is used as a proxy for a different plant, does the license permit that use? Legal review needed.
3. White-label behavior: Instance-specific plant visibility (instance_plant_item.is_visible) currently filters by plant. Proxy mappings should respect instance boundaries — a proxy image from a hidden plant should not leak into a restricted instance.
4. Retailer catalog sync: The /api/v1/plantCatalog endpoint uses transparent_images_aggregate to assess visual quality when matching retailer products. Should proxy-imaged plants count as "has image" for retailer matching purposes?