IntentIQ — The discovery engine that understands meaning, not just keywords

Keyword Dependency

Traditional search engines rely heavily on:

• Exact keyword matches
• Manual tagging
• Structured attributes

This causes 30%+ of searches to fail due to:

• Missing synonyms
• Typos
• Ambiguous queries
• Poor catalog tagging

Customer Vocabulary Mismatch

Shoppers describe products based on:

• Use case (“for camping in rain”)
• Outcome (“for fluffy milk foam”)
• Style (“minimalist cozy vibe”)

But catalogs are structured around:

• SKU attributes
• Manufacturer descriptions
• Technical specifications

Visual Search Gap

Current systems struggle to:

• Match aesthetics
• Detect style
• Align “vibe”

Conversion Loss

Up to 70% of browsing sessions end without purchase due to poor discovery.

Primary Customers (B2B)

• Shopify stores
• Mid-market e-commerce retailers
• Marketplaces
• DTC brands
• Home & fashion retailers

Secondary Customers

• Large enterprises
• Online grocery stores
• Electronics retailers
• B2B suppliers

End Users (Shoppers)

• Mobile-first buyers
• Voice search users
• Visual-first shoppers
• Non-technical customers

Core Search

• Semantic text search
• Natural language queries
• Conversational discovery
• Synonym expansion
• Intent clustering

Multimodal Search

• Image upload search
• Style matching
• Voice search support

Catalog Intelligence

• Auto-generated enriched descriptions
• Missing attribute detection
• Tag normalization
• Semantic metadata layer

Learning Loop

• Click feedback optimization
• Add-to-cart signal learning
• Query refinement engine

Admin Tools

• Search analytics dashboard
• Zero-result query report
• Custom intent rules
• Boosting controls

MVP Limits

• English-first
• Limited catalog size
• Text + image (voice beta)
• Single-store deployment

High-Level Architecture

Storefront (Web/Mobile)
        ↓
Search API Gateway
        ↓
Query Understanding Service
        ↓
Vector Search Engine
        ↓
Product Intelligence Engine
        ↓
Ranking & Personalization Layer
        ↓
Analytics & Learning Service

Architecture Style

• Microservices
• Vector-first search
• Event-driven learning
• Cloud-native deployment

Retailers

retailers
- id
- name
- api_key
- created_at

Products

products
- id
- retailer_id
- title
- description
- category
- price
- metadata_json
- embedding_vector

ProductImages

product_images
- id
- product_id
- image_url
- visual_embedding

Queries

queries
- id
- retailer_id
- query_text
- interpreted_intent_json
- timestamp

Interactions

interactions
- id
- query_id
- product_id
- action_type
- timestamp

Rankings

rank_logs
- id
- query_id
- ranking_json
- model_version

Search

POST /v1/search
POST /v1/search/image
POST /v1/search/voice

Catalog

POST /v1/catalog/sync
POST /v1/catalog/enrich
GET  /v1/catalog/status

Analytics

GET /v1/analytics/queries
GET /v1/analytics/conversion
GET /v1/analytics/zero-results

Admin

POST /v1/ranking/boost
POST /v1/ranking/rules

Frontend

• React / Next.js widget
• TypeScript
• TailwindCSS
• Headless UI

Backend

• Node.js (NestJS)
• PostgreSQL
• Redis
• REST + GraphQL optional

AI / ML

• Python FastAPI
• LLM APIs
• Sentence embeddings
• CLIP (image-text alignment)
• Vector DB (pgvector / Pinecone / Weaviate)
• XGBoost / LightGBM (ranking)

Infrastructure

• Docker
• Kubernetes
• AWS / GCP
• Terraform
• GitHub Actions

• API key authentication
• Tenant isolation
• Rate limiting
• TLS 1.3
• Encrypted embeddings
• DDoS protection
• Webhook verification
• Data access logging

SaaS Pricing

• Starter: $99/month
• Growth: $299/month
• Enterprise: custom pricing

Usage-Based

• Per 1,000 searches
• Per catalog size tier

Add-ons

• Personalization engine
• Visual AI upgrade
• Advanced analytics
• Multilingual models

Phase 1: Shopify App

• Launch in Shopify marketplace
• Offer 14-day free trial
• Early adopter pricing

Phase 2: DTC Brands

• Case studies
• Conversion lift demos
• Performance-based pricing

Phase 3: Mid-Market

• Sales outreach
• CRO agencies partnerships

Phase 4: Enterprise

• Custom integrations
• Headless commerce platforms

Pre-Launch

• Demo storefront
• A/B comparison vs keyword search
• Landing page + waitlist

Beta

• 5–10 stores
• Measure conversion lift
• Track zero-result drop

KPIs

• Conversion rate lift
• Add-to-cart rate
• Average order value
• Zero-result query %
• Revenue per search

Phase 1 (0–2 months)

• Semantic text search
• Vector indexing
• Basic analytics

Phase 2 (2–4 months)

• Image search
• Query refinement engine
• Ranking optimization

Phase 3 (4–6 months)

• Personalization layer
• Multilingual support
• Voice integration

Phase 4 (6+ months)

• Marketplace intelligence
• AI buying assistant
• Autonomous merchandising

• Catalog inconsistency
• Embedding drift
• Cold-start ranking
• Cost of inference
• Enterprise sales cycle
• Integration complexity
• Retailer trust
• Performance latency

• AI shopping assistant chatbot
• Predictive demand detection
• Dynamic product bundling
• Auto-tagging engine
• Voice commerce optimization
• AR-based product matching
• B2B procurement search
• Autonomous storefront optimization

IntentIQ — Pro Build Prompt (MVP)
You are a senior full-stack engineer building the MVP for “IntentIQ” (Semantic E-commerce Discovery Engine). Implement a production-ready but minimal system with:
A Next.js storefront search widget + admin dashboard
A NestJS (Node/TypeScript) backend API
A Python FastAPI AI service for semantic understanding, embeddings, ranking, and multimodal search
Use PostgreSQL for structured data, Redis for caching/queues, and a vector database (pgvector or Qdrant/Weaviate) for semantic retrieval.
The system must replace traditional keyword search with intent-aware semantic discovery, supporting text queries, image search, and conversational refinement — while remaining low-latency (<300ms retrieval target excluding LLM expansion).
CORE OBJECTIVE
Transform product discovery from keyword matching to meaning understanding, increasing:
Add-to-cart rate
Conversion rate
Search success rate
Revenue per search
GOALS (MVP)
1) Retailer Onboarding
Retailer can:
Create account
Generate API key
Connect store (Shopify REST API stub acceptable)
Sync product catalog
System must:
Fetch products (title, description, price, tags, images)
Normalize attributes
Generate semantic embeddings
Store structured + vector representations
2) Semantic Text Search
Customer can:
Enter natural language queries:
“coffee maker for small apartment”
“shoes for rainy hiking”
“minimalist desk lamp warm light”
System must:
Interpret intent (use case, constraints, style)
Generate query embedding
Retrieve semantically similar products
Apply ranking model
Return structured results
3) Image-Based Discovery
Customer can:
Upload image
Ask: “find something like this”
System must:
Generate visual embedding (CLIP)
Compare against product image embeddings
Blend visual similarity + metadata relevance
Return ranked results
4) Conversational Refinement
Customer can refine query:
“Cheaper”
“More modern”
“Only under $50”
“With fast shipping”
System must:
Maintain session context
Modify ranking filters
Recompute results without full re-query
Explain adjustments (optional MVP)
5) Learning & Feedback Loop
System must log:
Query
Returned products
Click events
Add-to-cart
Purchase
Use signals to:
Re-rank products
Improve query interpretation
Detect zero-result intent clusters
TECH STACK
Frontend (Widget + Admin)
Next.js (React), TypeScript
TailwindCSS
Headless UI
TanStack Query
Zustand
Web component build option for easy store embed
Backend API (NestJS)
NestJS + TypeScript
PostgreSQL (Prisma ORM)
Redis (BullMQ + caching)
REST API
API Key middleware
Rate limiting
AI Service (FastAPI)
Python FastAPI
Sentence-transformers (text embeddings)
CLIP (image embeddings)
XGBoost / LightGBM (learning-to-rank)
Optional LLM API for query expansion
Vector DB (pgvector or Qdrant)
Infrastructure
Docker Compose (local)
AWS ECS / Fly.io / Render
S3-compatible storage
Cloudflare CDN
GitHub Actions CI/CD
DELIVERABLES
A) Monorepo Structure
/apps/web
/apps/api
/apps/ai
/packages/shared
B) Docker Compose Services
postgres
redis
api
ai
C) Working Search Widget
Installable JS snippet
Configurable via API key
Autocomplete + suggestions
Instant results
D) Admin Dashboard
Search analytics
Zero-result queries
Top converting queries
Manual boost rules
Product reindex button
E) Seed Script
1 retailer
1,000 products
Pre-generated embeddings
200 mock search events
DATABASE SCHEMA (Prisma)
Retailer
id
name
apiKey
createdAt
Product
id
retailerId
title
description
category
price
currency
metadataJson
embeddingVector
createdAt
ProductImage
id
productId
imageUrl
visualEmbedding
QueryLog
id
retailerId
queryText
interpretedIntentJson
createdAt
Interaction
id
queryId
productId
actionType (click, cart, purchase)
createdAt
RankingLog
id
queryId
modelVersion
rankedProductIdsJson
API ENDPOINTS (NestJS)
Retailer
POST /v1/retailers
POST /v1/catalog/sync
POST /v1/catalog/reindex
Search
POST /v1/search
POST /v1/search/image
POST /v1/search/refine
Analytics
GET /v1/analytics/queries
GET /v1/analytics/conversion
GET /v1/analytics/zero-results
Ranking Controls
POST /v1/ranking/boost
POST /v1/ranking/rules
AI SERVICE ENDPOINTS (FastAPI)
POST /embed/text
Input:
product or query text
Output:
embedding vector
POST /embed/image
Input:
image file
Output:
visual embedding
POST /intent/parse
Input:
raw query
Output:
structured intent JSON:
use_case
constraints
style
price_range
sentiment
POST /search
Input:
query embedding
retailerId
filters
Output:
ranked product IDs
confidence score
POST /rank
Input:
candidate products
interaction history
Output:
reranked list
IMPLEMENTATION NOTES
Use hybrid search:
Vector similarity (semantic meaning)
BM25 fallback
Attribute filters
Precompute product embeddings on catalog sync.
Cache top queries in Redis.
Use approximate nearest neighbor search (ANN).
Keep search latency under 300ms for retrieval stage.
LLM expansion must be optional and cached.
Store modelVersion in ranking logs.
Zero-result queries must trigger fallback expansion.
SECURITY
API key per retailer
Tenant isolation (retailerId scoping)
Rate limiting
TLS 1.3
Webhook signature validation
Encrypted embeddings at rest
Input sanitization (prevent injection)
QUALITY BAR
Zod validation on all endpoints
Typed error responses
Correlation IDs
Structured logs
Unit tests:
embedding pipeline
ranking logic
filter merging
Integration tests:
catalog sync → search → click → rerank
Load test 1,000 concurrent search queries
SUCCESS METRICS
Search latency < 300ms
Zero-result queries < 5%
Conversion lift > 8%
Add-to-cart lift > 10%
Revenue per search ↑
API uptime > 99.9%
FINAL INSTRUCTION
Now implement the IntentIQ MVP end-to-end following this specification.
Prioritize:
Semantic accuracy
Low latency
Ranking explainability
Retailer data isolation
Conversion impact
Build it as if it will power the search layer for the next billion-dollar e-commerce brand.