Vectr: Natural Language Image Search

Vectr

Vectr is an AI-powered image search application template that automatically generates descriptions for uploaded images and indexes them for semantic search.

✨ Features

• 📤 Drag-and-drop image uploads with Vercel Blob Storage
• 🤖 AI-powered image descriptions using Grok 2 Vision
• 🔍 Semantic search with Upstash Vector Search (stores metadata too!)
• 🔄 Resilient processing with Vercel Workflow automatic retries
• 🎨 Beautiful UI built with shadcn/ui and Tailwind CSS
• 💰 Incredibly cheap - No database needed!

🚀 How It Works

When you upload an image, Vectr automatically:

1. 💾 Stores the image in Vercel Blob Storage
2. 🧠 Generates a detailed description using Grok 2 Vision AI
3. 🔎 Indexes the description AND metadata in Upstash for semantic search

Loading diagram...

🏗️ Architecture

Workflow Steps

Each step in the image processing workflow is isolated and runs on a separate serverless function with automatic retries:

Step 1: Upload Image (upload-image.ts)

• 💾 Uploads to Vercel Blob Storage
• ⏱️ Handles rate limiting with 1-minute retry delays
• 🔄 Maximum 3 retry attempts
• ❌ Fatal error on quota exceeded or invalid files

Step 2: Generate Description (generate-description.ts)

• 🤖 Uses Grok 2 Vision AI to analyze the image
• ⏱️ Handles rate limiting with 5-minute retry delays
• 🔄 Maximum 5 retry attempts
• ❌ Fatal error on invalid/unsupported images

Step 3: Index Image (index-image.ts)

• 🔎 Indexes description AND blob metadata in Upstash
• 💾 Stores all image data (url, size, contentType, etc.) as metadata
• ⏱️ Handles rate limiting with 1-minute retry delays
• 🔄 Maximum 5 retry attempts
• ❌ Fatal error on invalid data

Error Handling

Vectr uses sophisticated error handling to ensure reliable processing:

• 🔄 RetryableError: Temporary failures (rate limits, network issues, timeouts)
• ❌ FatalError: Permanent failures (invalid data, constraint violations)
• 📊 Context-aware retries: Each step tracks attempt count and timestamps
• 🎯 Smart HTTP responses: 400 for fatal errors, 500 for retryable errors

🛠️ Tech Stack

• ⚡ Framework: Next.js 15 with App Router and React 19
• 🔄 Workflow: Vercel Workflow (alpha)
• 🤖 AI: Grok 2 Vision via Vercel AI SDK
• 🔍 Search & Storage: Upstash Vector Search (stores metadata too!)
• 💾 Blob Storage: Vercel Blob Storage
• 🎨 UI: shadcn/ui + Tailwind CSS 4
• 🔒 Type Safety: TypeScript + Zod

🚀 Deploy to Vercel

The easiest way to deploy Vectr is using the Vercel Marketplace:

During deployment, you'll be prompted to set up:

1. 🔍 Upstash Vector Search - Semantic search + metadata storage
2. 💾 Vercel Blob Storage - Image storage

Both services have generous free tiers and will be automatically configured. No database needed!

💻 Local Development

Prerequisites

• 🟢 Node.js 18+
• 📦 pnpm (recommended)

Setup

1. Clone the repository:

1
git clone https://github.com/your-username/vectr.git
2
cd vectr

1. Install dependencies:

1
pnpm install

1. Set up environment variables:

Create a .env.local file with:

1
# Upstash Search
2
UPSTASH_SEARCH_URL="https://..."
3
UPSTASH_SEARCH_TOKEN="..."
4

5
# Vercel Blob (OIDC) — provided by `vercel env pull`
6
VERCEL_OIDC_TOKEN="..."   # short-lived, auto-rotated
7
BLOB_STORE_ID="..."
8

9
# AI Gateway Key (only needed locally)
10
AI_GATEWAY_API_KEY="..."

1. Run the development server:

1
pnpm dev

Open http://localhost:3000 to see your app.

📜 Scripts

• 🚀 pnpm dev - Start development server with Turbopack
• 🏗️ pnpm build - Build for production
• ✅ pnpm check - Run linting checks
• ✨ pnpm format - Format code with Biome

📁 Project Structure

1
vectr/
2
├── app/
3
│   ├── actions/
4
│   │   └── search.ts                 # Server action for search
5
│   ├── api/
6
│   │   └── upload/
7
│   │       ├── route.ts              # Workflow route handler
8
│   │       ├── upload-image.ts       # Step 1: Upload to Blob
9
│   │       ├── generate-description.ts  # Step 2: AI description
10
│   │       └── index-image.ts        # Step 3: Index with metadata
11
│   ├── layout.tsx
12
│   └── page.tsx
13
├── components/
14
│   ├── header.tsx
15
│   ├── results.tsx
16
│   ├── upload-button.tsx
17
│   └── uploaded-images-provider.tsx
18
├── lib/
19
│   └── utils.ts
20
└── package.json

🔐 Environment Variables

📊 Observability

Vectr includes comprehensive logging for monitoring and debugging:

• 🔄 [WORKFLOW] - Workflow-level events and timing
• 🔧 [stepId] - Step-level events with unique identifiers
• 🌐 [API] - HTTP request/response logging

All logs include timestamps, attempt counts, and duration metrics.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Our Contributing Guide has more information on how to get started.

📄 License

MIT