Optimal Auction Builder — Scope & Build

Full scope, feature list, and downloadable source ZIP for the Optimal Auction Builder module — including Lot Styles, Build Auction Lots, and Build a Lot with AI.

Optimal Auction Builder Source (ZIP)

21 files · ~59 KB · 1 page, 4 optimal-auction components, 7 lot components, 1 lib, 5 backend functions, 3 entities

Optimal Auction Builder — Scope & Feature Spec

Overview

The Optimal Auction Builder is the AI brain of AuctionSnap's cataloging stage. It takes your pool of graded Bulk Upload cards and turns them into a sellable auction: it analyzes the market, decides which cards to grade vs sell raw vs group, groups low-value cards into themed lots, sequences the whole catalog for maximum bidding momentum, and lets you review/edit/accept each lot before it lands in your Auction Library. It also includes a natural-language "Build a Lot with AI" prompter and a visual showcase of every lot display style.

Primary Goal

Maximize auction profit and bidder engagement by making smart, data-driven decisions for every card — and giving the auctioneer full manual control to override anything.

Pages & Routes

  • OptimalAuction — /OptimalAuction — the builder page with two tabs: Optimal Sequence and Auction Lots.

Source Files (included in the ZIP)

Frontend — Page

  • src/pages/OptimalAuction.jsx — the builder page (tabs, build buttons, lot review grid, bulk actions, modals).

Frontend — Optimal Auction Components (src/components/optimalauction/)

  • MarketAnalysisPanel.jsx — live market intelligence + sports/players/brands hotness bars.
  • AuctionCatalog.jsx — the sequenced catalog view (opening → star → mid → premium → closing).
  • LotStyleShowcase.jsx — visual gallery of all 11 lot display styles with sample previews.
  • PromptedLotBuilder.jsx — natural-language "Build a Lot with AI" prompter + option picker.

Frontend — Auction Lot Components (src/components/auctionlots/)

  • LotCard.jsx — one reviewable lot (preview, accept/reject/edit/add, style switcher, expandable card list).
  • LotPreview.jsx — renders the composed lot image (or a live CSS fallback).
  • LotAcceptModal.jsx — accept a lot → pick an auction → save to Media Library.
  • LotEditModal.jsx — edit a lot's cards, title, description, and display style.
  • AddCardsModal.jsx — add available graded cards to a lot.
  • BulkAcceptModal.jsx — accept many lots at once into one auction.
  • DownloadLotButton.jsx — download a lot's composed image.

Frontend — Shared Lib

  • src/lib/lotAcceptHelper.js — composes the lot image + builds MediaLibrary records (composed image + per-card front/back).

Backend Functions

  • base44/functions/buildOptimalAuction/entry.ts — market analysis + grade/raw/group decisions + lot grouping + auction sequencing + DB persist.
  • base44/functions/buildAuctionLots/entry.ts — rules-based lot builder (singles, 4/6/20-packs) with display-style assignment + rich descriptions.
  • base44/functions/buildPromptedLots/entry.ts — LLM-powered natural-language lot builder (proposes 3–6 options).
  • base44/functions/composeLotImage/entry.ts — server-side image composer (renders cards into one image by display style).
  • base44/functions/selectBulkCards/entry.ts — AI auction selection (solo vs group recommendations).

Entities

  • base44/entities/BulkUploadCard.jsonc — the graded card pool (source of lots).
  • base44/entities/MediaLibrary.jsonc — accepted lots land here.
  • base44/entities/AuctionItem.jsonc — auction item records.

Features

1. Two Build Modes (tabs)

  • Optimal Sequence — "Build Optimal Auction" runs the full buildOptimalAuction pipeline: market analysis → grade/raw/group decisions → lot grouping → auction sequencing. Shows a summary, the Market Analysis panel, and the sequenced Auction Catalog.
  • Auction Lots — "Build Auction Lots" runs buildAuctionLots, a rules-based lot builder that produces reviewable, editable lots (singles, 4-packs, 6-packs, 20-packs) with composed preview images.

2. Lot Styles (11 display styles)

Every lot is arranged in one of these visual styles. The AI picks one based on card count, but you can change it anytime via the style dropdown on each LotCard or in the Lot Edit modal. The Lot Styles button opens LotStyleShowcase — a visual gallery of all styles rendered with sample cards:

  • Single (1 card) — One card, for high-value solo lots.
  • Stack (up to 5) — Cascading pile; top card featured, edges of others peeking.
  • Virtual Stack (20+) — Thick block representing a bulk lot, 1–2 featured cards in front.
  • Fan (up to 6) — Cards fanned out in an arc.
  • 2×2 Grid (4) — Four cards in a neat square.
  • 3×2 Grid (6) — Six cards, three across.
  • 4×2 Grid (8) — Eight cards, four across.
  • 3×3 Grid (9) — Nine cards in a square grid.
  • 4×3 Grid (12) — Twelve cards, four across.
  • 4×4 Grid (16) — Sixteen cards in a square.
  • 5×4 Grid (20) — Twenty cards — the biggest grid.

The server-side composeLotImage function renders the chosen style into a single composed JPEG (white background, bilinear-resized cards, letterboxed) and uploads it — that composed image becomes the lot's primary thumbnail in the library.

3. Build Auction Lots (rules-based AI logic)

buildAuctionLots groups all graded cards into lots using these deterministic rules (most valuable cards first):

  1. Single Cards — raw market value > $2.00 → sold individually.
  2. 4-Card Lots — combined value > $5.00. Binding priority: Same Player → HOFers → Rookies.
  3. 6+ Card Lots — combined value > $10.00. Binding priority: Same Set → Same Player → HOFers & Rookies.
  4. 20+ Card Lots — combined value > $20.00. Binding: Same Sport (bulk).
  5. Leftovers — remaining cards form mixed bulk lots.

Each lot gets:

  • A display style auto-picked from the card count (small → fan/grid_2x2, medium → grid_3x2/4x2, large → grid_3x3/4x3/4x4, 20+ → virtual_stack).
  • A lot name generated from the binding (e.g. "Baseball Hall of Famers Lot (4 cards)").
  • A rich auction-catalog description with: opening summary, binding/theme explanation, featured players with HOF/RC annotations, brand/year/era context, card-by-card highlights (small lots) or top-cards + value distribution (large lots), condition overview, value summary, and collector appeal closing.
  • Cards sorted by value descending (top card shows in stack/fan).
  • Rejected-grouping memory — if you reject a lot, its card signature is remembered so buildAuctionLots won't recreate the exact same grouping on rebuild; the cards get redistributed into other lots.

4. Build a Lot with AI (natural-language prompter)

The "Build a Lot" button opens PromptedLotBuilder. You type a request (e.g. "Make a lot of 10 Dodgers cards" or "Make a lot of 4 higher-priced rookies"), and buildPromptedLots:

  • Sends your prompt + the pool of available graded cards to the LLM.
  • The LLM proposes 3–6 different lot options — each with a genuinely different card combination AND a different display style.
  • Each option includes: lot name, rich catalog description, binding label, display style, reasoning, card count, estimated value, and card thumbnails.
  • You pick one option → it's added to the review queue and its composed image is generated.
  • Example prompts are provided as one-click chips.

5. Optimal Sequence (full pipeline)

buildOptimalAuction runs the complete AI pipeline:

  1. Market Analysis — aggregates hotness by sport, player, and brand from the graded cards (count + avg value + trend score + trend direction).
  2. Live Market Context — an LLM with web search returns current hottest sports, trending players, hot brands, raw-vs-graded advice, and key recommendations.
  3. Grade vs Raw vs Group decisions — per card:
    • Raw ≤ $2.00 → group into a lot.
    • High value (> $50) or strong grading ROI (ROI > 20% & PSA-10 prob > 15%) → grade then sell solo.
    • Mid value (> $10, or hot category > $5) → sell raw solo.
    • Low-mid → group.
  4. Lot Grouping — low-value cards grouped by affinity passes: Same Player (4) → Same Brand & Year (6) → Same Brand (8) → Same Sport & Era (8) → Same Sport (10) → Mixed Commons (10).
  5. Auction Sequencing — optimal flow for max bids:
    • Open strong (mid-tier item or top lot).
    • Interleave lot → mid → star pattern to keep bidders engaged.
    • Drain remaining items.
    • Close with the single most valuable item (big finish).
    • Positions tagged: opening, star, mid, premium, closing, lot.
  6. Persist — writes selected_for_auction, auction_sequence, auction_role (solo_grade / solo_raw / lot_member), and group_id back to each card.

6. Lot Review & Editing

  • LotCard — each lot shows: number, type badge, name, composed preview image, estimated value, card count, binding, and a style dropdown.
  • Accept → LotAcceptModal picks an auction → lotAcceptHelper composes the image and builds MediaLibrary records (1 composed lot image as zoom_out + each card's front/back, all sharing the lot number).
  • Reject → removes the lot and remembers its signature so it won't reappear on rebuild.
  • Edit → LotEditModal changes cards, title, description, and display style; removed cards go back to the pool.
  • Add Cards → AddCardsModal adds available graded cards to the lot.
  • Change Style → dropdown regenerates the composed image instantly.
  • Download → DownloadLotButton downloads the composed image.
  • Expand → see every card with HOF/RC badges and individual values.

7. Bulk Actions

  • Select lots via checkbox → sticky bulk action bar.
  • Accept Selected → BulkAcceptModal accepts many lots into one auction at once.
  • Reject Selected → rejects all selected lots (signatures remembered).
  • Select all visible / Clear.

8. Filtering & Summary

  • Filter by lot type: All, Singles, 4-Packs, 6+ Packs, 20+ Packs (with counts).
  • Summary cards: Total Lots, Singles, 4-Packs, 6+ Packs, 20+ Packs, Est. Value.
  • Available cards indicator: total cards, graded count, lots in review, available to add.

9. Persistence

  • Lots, summary, and rejected signatures are saved to localStorage so they survive reloads and tab switches until acted on.
  • The transient composing flag is stripped on save so a reload never shows a stuck spinner.

Data Flow

Graded BulkUploadCards
  → "Build Optimal Auction" (buildOptimalAuction) → market analysis + sequence + DB persist
  → "Build Auction Lots" (buildAuctionLots) → reviewable lots + composed images
  → "Build a Lot" (buildPromptedLots) → AI-proposed custom lots
  → Review queue (LotCard) → edit / add cards / change style / accept / reject
  → Accept (LotAcceptModal) → composeLotImage + lotAcceptHelper → MediaLibrary records
  → Auction Library (gallery)

Known Behaviors / Decisions

  • Both builders require graded cards — grade cards in Bulk Upload first.
  • buildAuctionLots is deterministic rules-based; buildPromptedLots is LLM-based; buildOptimalAuction is a hybrid (deterministic decisions + LLM market context).
  • Composed lot images are rendered server-side to avoid cross-origin canvas taint.
  • Accepting a lot saves a composed zoom_out image as the primary thumbnail plus individual front/back images — all sharing the lot number so they group in the gallery.
  • If the composed image is missing, lotAcceptHelper refuses to save (prevents a single player card becoming the lot thumbnail).
  • Rejected lots are remembered by signature so rebuilds redistribute cards instead of recreating the same lot.
  • The sequence's closing item is always the single most valuable lot/card.

Dependencies

  • Entities: BulkUploadCard, MediaLibrary, AuctionItem
  • Backend functions: buildOptimalAuction, buildAuctionLots, buildPromptedLots, composeLotImage, selectBulkCards
  • Integrations: Core.InvokeLLM (market context + prompted lots), Core.UploadFile (composed images)
  • Libs: lotAcceptHelper
  • Packages: react-query, lucide-react, shadcn/ui