How vercel-labs/semantic-image-search works
Project type and purpose
• This is a full‑stack AI‑driven image search web application built on Next.js 14’s App Router.
• The frontend is React (Server & Client Components), the backend is Node (Next.js Server Actions & API routes), and it integrates with AI model providers (OpenAI, Gemini, etc.), Vercel Blob (image storage), Vercel Postgres + pgvector (vector DB via Drizzle ORM), and Vercel KV (cache).
File structure analysis
• Top level: configuration (next.config.mjs, drizzle.config.ts, Tailwind, TS, ESLint).
• app/: Next.js routes (layout.tsx, page.tsx) and global CSS.
• components/: UI building blocks (shadcn/ui + custom React components).
• lib/:
• lib/ai/: CLI scripts for indexing pipeline (upload → metadata → embed & save).
• lib/db/: Drizzle ORM setup, schema, and API wrappers.
• lib/hooks/: custom React hooks.
• lib/utils.ts: shared helpers.
• public/: static assets.
• package.json (scripts for upload, generate-metadata, embed-and-save, dev).
• .env.example: environment variables for AI provider, Postgres, KV, Blob.
README insights
• Emphasizes: React Server Components with Suspense, Server Actions; Vercel AI SDK for multimodal prompts; caching in Vercel KV; embeddings in Vercel Postgres via pgvector; storage in Vercel Blob; styling with shadcn/ui (Tailwind + Radix).
a. Main components
• Client browser (user)
• Next.js Frontend (React Client Components)
• Next.js Server (Server Components, Server Actions, API Routes)
• AI Model Providers (OpenAI / Gemini / Anthropic / custom via Vercel AI SDK)
• Vercel Blob (image storage)
• Vercel Postgres + pgvector (embedding DB)
• Drizzle ORM (schema & queries)
• Vercel KV (query cache)
• CLI Indexing Pipeline (scripts in lib/ai)
b. Relationships & data flow
1. User → Next.js page (Client Component) → triggers Server Action or fetch call
2. Next.js Server → Vercel KV (lookup cache)
3. On cache miss → Query Postgres via Drizzle (vector search)
4. If user uploads/indexes images: CLI upload → Blob; generate-metadata → AI SDK generates titles/descriptions; embed-and-save → AI SDK computes embeddings & writes to Postgres
5. Server streams images and metadata back to client (via Vercel AI SDK streaming or Next.js streaming)
6. Optionally: cache popular queries back into KV
7. External AI models are invoked by the AI SDK from both Server Actions (on demand) and CLI scripts.
c. Architectural patterns
• React Server Components & Suspense for data fetching
• Server Actions for mutations (image search queries)
• CLI pipeline for batch processing
• Cache‑Aside pattern: KV cache in front of Postgres
• Separation of concerns: UI / data‑access / AI logic
d. Key technologies
• Next.js 14, React RSC, Server Actions
• Vercel AI SDK for prompting, generation, embedding, streaming
• Drizzle ORM + pgvector on Vercel Postgres
• Vercel KV for caching
• Vercel Blob for file storage
• Tailwind CSS + Radix UI (shadcn/ui)