# vercel-labs/semantic-image-search architecture

> Architecture diagram of the GitHub repository vercel-labs/semantic-image-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vercel-labs/semantic-image-search
- Repository: https://github.com/vercel-labs/semantic-image-search

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Swimlanes
    subgraph "User & Frontend"
        direction TB
        Browser["User Browser"]:::frontend
        ClientComp["React Client Components"]:::frontend
        UIStack["UI Libraries (Tailwind CSS + Radix via shadcn/ui)"]:::frontend
        Globals["Global Styles"]:::frontend
        Router["Next.js App Router\n(layout.tsx & page.tsx)"]:::frontend
    end

    subgraph "Backend & Server"
        direction TB
        ServerComp["React Server Components & Suspense"]:::backend
        ServerActions["Next.js Server Actions & API Routes"]:::backend
    end

    subgraph "CLI Indexing Pipeline"
        direction TB
        Upload["Upload Script\n0-upload.ts"]:::backend
        GenMeta["Generate Metadata\n1-generate-metadata.ts"]:::backend
        EmbedSave["Embed & Save\n2-embed-and-save.ts"]:::backend
        AIUtils["AI Utils\nutils.ts"]:::backend
    end

    subgraph "Storage & Cache"
        direction TB
        KV["Vercel KV\n(Cache)"]:::cache
        Postgres["Vercel Postgres + pgvector"]:::storage
        Blob["Vercel Blob\n(Image Storage)"]:::storage
    end

    subgraph "Database Layer"
        direction TB
        Schema["Drizzle ORM Schema\nschema.ts"]:::backend
        DBIndex["Drizzle ORM Setup\nindex.ts"]:::backend
        API["DB API Wrappers\napi.ts"]:::backend
    end

    subgraph "Utilities & Config"
        direction TB
        Hooks["Shared Hooks\nuse-shared-transition.tsx"]:::backend
        Utils["Shared Utils\nutils.ts"]:::backend
        NextConfig["Next.js Config\nnext.config.mjs"]:::backend
        DrizzleConfig["Drizzle Config\ndrizzle.config.ts"]:::backend
        TailwindConfig["Tailwind & PostCSS\nconfigs"]:::backend
        TSConfig["TypeScript & ESLint\nconfigs"]:::backend
        EnvExample["Env Definition\n.env.example"]:::backend
    end

    subgraph "External AI Services"
        direction TB
        AIProviders["OpenAI / Gemini / Anthropic\n(Vercel AI SDK)"]:::external
    end

    %% Connections: Frontend to Backend
    Browser -->|"interacts via UI"| ClientComp
    ClientComp -->|"uses Router"| Router
    Router -->|"renders & fetches"| ServerComp
    Router -->|"calls Actions/API"| ServerActions
    ClientComp -->|"imports styles"| Globals
    ClientComp -->|"imports components"| UIStack

    %% Backend to Cache & DB
    ServerActions -->|"cache lookup"| KV
    KV -->|"on miss"| API
    API -->|"vector search"| Postgres
    API -->|"uses schema & setup"| Schema
    API -->|"uses schema & setup"| DBIndex

    ServerComp -->|"fetch data via Actions/API"| ServerActions

    %% CLI Pipeline flows
    Upload -->|"stores images"| Blob
    GenMeta -->|"metadata gen"| AIProviders
    GenMeta -->|"reads images"| Blob
    EmbedSave -->|"generates embeddings"| AIProviders
    EmbedSave -->|"writes embeddings"| Postgres
    Upload -->|"uses AI utils"| AIUtils
    GenMeta -->|"uses AI utils"| AIUtils
    EmbedSave -->|"uses AI utils"| AIUtils

    %% AI on-demand
    ServerActions -->|"invoke embedding/generation"| AIProviders
    ServerComp -->|"stream images & metadata"| ClientComp

    %% Optional caching
    ServerActions -->|"cache popular queries"| KV

    %% Utility dependencies
    ServerComp --> Hooks
    ServerActions --> Utils

    %% Click Events
    click Router "https://github.com/vercel-labs/semantic-image-search/blob/main/app/layout.tsx"
    click Router "https://github.com/vercel-labs/semantic-image-search/blob/main/app/page.tsx"
    click Globals "https://github.com/vercel-labs/semantic-image-search/blob/main/app/globals.css"
    click UIStack "https://github.com/vercel-labs/semantic-image-search/tree/main/components"
    click Upload "https://github.com/vercel-labs/semantic-image-search/blob/main/lib/ai/0-upload.ts"
    click GenMeta "https://github.com/vercel-labs/semantic-image-search/blob/main/lib/ai/1-generate-metadata.ts"
    click EmbedSave "https://github.com/vercel-labs/semantic-image-search/blob/main/lib/ai/2-embed-and-save.ts"
    click AIUtils "https://github.com/vercel-labs/semantic-image-search/blob/main/lib/ai/utils.ts"
    click Schema "https://github.com/vercel-labs/semantic-image-search/blob/main/lib/db/schema.ts"
    click DBIndex "https://github.com/vercel-labs/semantic-image-search/blob/main/lib/db/index.ts"
    click API "https://github.com/vercel-labs/semantic-image-search/blob/main/lib/db/api.ts"
    click Hooks "https://github.com/vercel-labs/semantic-image-search/blob/main/lib/hooks/use-shared-transition.tsx"
    click Utils "https://github.com/vercel-labs/semantic-image-search/blob/main/lib/utils.ts"
    click NextConfig "https://github.com/vercel-labs/semantic-image-search/blob/main/next.config.mjs"
    click DrizzleConfig "https://github.com/vercel-labs/semantic-image-search/blob/main/drizzle.config.ts"
    click TailwindConfig "https://github.com/vercel-labs/semantic-image-search/blob/main/tailwind.config.ts"
    click TailwindConfig "https://github.com/vercel-labs/semantic-image-search/blob/main/postcss.config.mjs"
    click TSConfig "https://github.com/vercel-labs/semantic-image-search/blob/main/tsconfig.json"
    click TSConfig "https://github.com/vercel-labs/semantic-image-search/blob/main/.eslintrc.json"
    click EnvExample "https://github.com/vercel-labs/semantic-image-search/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#cfe2ff,stroke:#084298,color:#084298
    classDef backend fill:#d1e7dd,stroke:#0f5132,color:#0f5132
    classDef storage fill:#f8d7da,stroke:#842029,color:#842029
    classDef cache fill:#fff3cd,stroke:#664d03,color:#664d03
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
