Coffee data and discoverability architecture
Research date 12 November 2026. Product proposal and verified platform constraints.
Decision
Coffee Kit should maintain a reviewed coffee catalog in merchant-owned Shopify data, with an app database for workflow state, evidence, integrations and audit history. The product is the repeatable path from a new coffee source document to a coherent selling experience. Extraction alone is unlikely to carry the premium price.
Ownership and migration
Use non-reserved merchant-owned namespaces/types for public facts. Reuse compatible existing definitions and Shopify standard/category attributes before introducing a new definition. Shopify distinguishes merchant-owned definitions from reserved app-owned definitions; granting merchant edit access does not change ownership. App-owned definitions are deleted on uninstall and values have no guaranteed retention period. See metafield definitions and metaobject lifecycle.
Proposed namespace coffee_kit is illustrative, pending collision audit against existing Coffeetale definitions. Definition creation → validated value writes → read-back verification is the publishing sequence. Data visible through Liquid still needs suitable Storefront API access for agencies and headless use. Never make customer preference or supplier-private data public alongside product facts. Metafield ownership, metaobject ownership.
Offer three explicit source choices per field: use existing compatible field; copy once into canonical field; or managed mapping with conflict review. A mapping table stores source identifier/type, target identifier/type, converter, precedence, last-seen digest and provenance. Never run blind bidirectional synchronization. Treat a merchant edit after import as a conflict, not permission to overwrite. Schema versioning must preserve existing field identifiers; destructive migration requires a separate approved operation and backup.
On uninstall, leave approved merchant-owned content intact, stop jobs, revoke credentials, and follow Shopify data-deletion obligations for app-held customer data. App blocks and app-hosted services cease, so persistent data does not promise persistent paid UI. Coffeetale can independently render supported merchant-owned fields; external themes need their own renderer after uninstall. Export reviewed records, mappings and configuration in JSON/CSV.
Minimal domain model
| Object | Owns | Avoid |
|---|---|---|
| Shopify Product | Commercial product title, description, category, publication | Reimplementing Shopify product editor |
| Shopify Variant | Sellable bag size/grind SKU, money, inventory item | AI inventing price, stock or SKU |
| Coffee lot | Origin, producer/cooperative, harvest, process, varieties, sourced tasting notes | Treating farm as mandatory or replacing past lot identity |
| Roast offering | Product/lot association, roast descriptor, decaf method, brew suitability | Storing roast on an eternal farm record |
| Producer/origin | Reusable factual entities where needed | Too many metaobjects for a one-product merchant |
| Sensory assessment | Axis values, scale, assessor/source/date | Deriving precise chart values from adjectives |
| Brew recipe | Method, recipe parameters, steps, provenance | Presenting a generated suggestion as roaster-approved |
| Experience configuration | Named grid, finder, builder, approved catalog filter, style profile | Duplicated conflicting settings across app and editor |
| Private customer preferences | Explicit stated choices with consent and provenance | Inferring sensitive data or public customer metafields |
Not every record needs every field. Launch requires enough truth for sale: product identity, price/variant mapping, availability, selected source-backed descriptors. Sparse products should still render elegantly.
Import and publication workflow
- Connect existing products; classify candidates with manual corrections.
- Upload bag photographs, PDF sheets, CSV or text. Select create draft product versus enrich existing product; detect duplicates by identifiers and image/file hashes.
- Extract into strict JSON containing value, original text, source file/page/region, confidence, and state: observed, normalized, suggested or unknown.
- Normalize units and vocabulary deterministically. Preserve original wording and multi-origin blends; separate tasting notes from ingredients/allergens. No external search enrichment by default.
- Run validations and cross-source conflict detection. A source screenshot is untrusted content, not instructions to execute.
- Show a review queue with source and product preview side by side. Require a person to approve prices, SKU/variant structure, publication, inventory and uncertain sensory facts.
- Create a draft or patch approved fields idempotently, verify Shopify errors plus read-back, then publish by explicit merchant action.
- Emit catalog-change events. Refresh derived finder eligibility and storefront configuration; flag subscription implications for review.
- Maintain undo records of previous values and a source audit. Undo must first check whether another actor edited the field since publication.
The app should handle merchandise inventory links but not roast planning, sourcing or warehouse operations. If a rotating subscription uses a permanent club SKU, the developer must explicitly solve which physical coffee's stock is decremented; a descriptive lot label alone does not do that.
AI provider and cost test
Start a bake-off rather than fine-tuning. Google currently positions Gemini 3.5 Flash-Lite for low-cost multimodal processing. Its observed standard rate is $0.30 per million input tokens and $2.50 per million output tokens; model IDs and availability must be rechecked at implementation. Older 2.5 availability/migration notices make it a poor hard-coded new-project assumption. Current pricing, model.
Illustrative request budget: 8,000 input and 1,500 output tokens → $0.00615 inference. Two such passes → $0.0123. A 20% retry allowance → $0.01476. One hundred such imports → $1.476 inference. These are modeled token counts, not measured photo/PDF costs, and exclude file storage, rendering/OCR, failed jobs, provider fallback, hosting and human review. At an assumed $30/hour, two minutes of manual assistance costs $1, far more than this illustrative inference. Price for the supported outcome, not tokens.
Use paid commercial processing terms appropriate to merchant documents. Keep a provider adapter and per-job budget. Benchmark a currently available second multimodal provider at implementation; do not commit to the cheapest advertised model without accuracy results. Structured JSON prevents format errors, not incorrect facts. Structured output guidance, PDF handling.
Proposed evaluation: 100 representative sources across languages, glare, curved bags, blends, decaf, experimental processing, incomplete labels and contradictory sources. Human-author gold annotations; hold out at least 30. Measure source-backed field precision, omission recall, fabricated facts, correct units/variant mapping, review minutes and fully loaded cost. Proposed release gates: zero invented critical facts on the holdout, 99% precision for auto-accepted facts, every unsupported field left empty, all price/stock changes reviewed. Confidence thresholds must be calibrated empirically.
Search and agent visibility
Make approved facts readable in initial HTML, with clear product titles, internal links, working canonical URLs, accurate offers/availability and useful images. Add or coordinate Product/Offer markup rather than emitting contradictory competing Product entities. Use ProductGroup/variant markup where appropriate, validated against Google's current requirements. A generic coffee rich-result type was not established in this research. Google supports Product features, with eligibility rules, not guaranteed rankings. Google product structured data.
Use schema.org additionalProperty for relevant descriptors without a dedicated schema property. It is a semantic representation, not evidence that Google will display roast/altitude as a rich-result field. Prefer a dedicated property where applicable. Schema definition.
Google says its AI search experiences use the established SEO foundations and do not require special AI markup; its guide explicitly says LLMS.txt does not help Google rankings. Therefore sell accurate, accessible coffee information and reduce missing-data work; never promise AI citations, traffic or incremental sales from metadata alone. AI search guidance, AI optimization guide.
Local cafe discovery is a separate job: correct location pages, hours/address and Google Business Profile, plus appropriate LocalBusiness markup. Product enrichment alone does not solve local SEO. Local business guidance.
Shopify already exposes products through agentic storefront channels, subject to channel requirements and merchant controls; custom coffee fields are not automatically proven to affect every agent ranking. Audit the real channel payload and product eligibility before promising coverage. Shopify agentic storefronts.
Storefront delivery and performance
Theme app extensions currently enforce 100 KB total Liquid, 10 MB total files, and 30 blocks. Schema-referenced compressed CSS/JS guidance is 100 KB/10 KB respectively; these suggested thresholds are distinct from enforced limits. Configuration and limits.
Extract small semantic renderers rather than copying the full Hydra stack. Render useful coffee facts and core purchase choices in Liquid; defer interactive builder code until needed. Use Shopify CDN assets, scoped styles, a shared design-token adapter and component-level dependencies. App proxies can support dynamic services but should not replace all product content with network-dependent JavaScript.
Coffeetale reuse needs a version handshake and feature capability contract; presence of the theme name alone does not prove compatible code. External themes get self-contained scoped assets. Avoid the promise of zero performance impact: measure cold cache, mobile CPU, JS bytes, layout shift and add-to-cart timing with disabled, minimal and full features.
Agency interface
Read approved coffee facts directly from Shopify Storefront API with public product data only. Expose versioned Coffee Kit endpoints for resolved experience configuration and finder evaluation; authentication and tenant isolation protect merchant configuration writes. Provide signed server-to-server events, a read-only demo dataset, schema changelog, CSS-free rendering examples and capability discovery. Provider credentials and contract writes stay server-side. Agencies can replace presentation without rebuilding extraction/review/configuration. Do not market a full stable public API until its compatibility policy and integration tests exist.
Evidence limits
No extraction benchmark, live schema migration, storefront performance test, Google eligibility test or agency API was implemented in this study. These are explicit developer acceptance tasks. Sources were read on 12 November 2026; platform documentation may change.
Second model candidate
Anthropic currently advertises Claude Haiku 5.5 at $0.10 input/$0.50 output per million tokens for prompts up to 100,000 tokens, with higher rates above that threshold. It accepts image inputs and the platform documents PDF processing. At the same illustrative 8,000-input/1,500-output token count, one request is $0.00155; tokenization and image accounting differ, so this is not an equal-quality benchmark. Compare it with Gemini on the gold dataset before choosing a default. Haiku 5.5 specification, pricing, PDF support.
Source: data-discovery-evidence.md The complete Markdown handoff and private datasets remain in the local project. This web edition includes selected supporting visuals and scenario downloads.