# azure-samples/azure-ai-vercel-rag-starter architecture

> Architecture diagram of the GitHub repository azure-samples/azure-ai-vercel-rag-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure-samples/azure-ai-vercel-rag-starter
- Repository: https://github.com/azure-samples/azure-ai-vercel-rag-starter

## Overview

##### Project Type and Purpose
- This is a full-stack Next.js application using the Vercel AI SDK to implement Retrieval-Augmented Generation (RAG).
- The frontend is a React/Next.js UI (with Tailwind CSS and Framer Motion) that streams AI chat responses.
- The backend is a set of Next.js route handlers (API routes) that orchestrate calls to Azure Cognitive Search and Azure OpenAI for vector retrieval and generative chat.

##### File Structure Analysis
- Top-level: configuration files (Dockerfile, Next.js configs, CI/CD workflows).
- `/app/(preview)/api/chat/route.ts`: serverless API route for chat requests.
- `/app/(preview)`: Next.js 13 app directory with layout, global CSS, and page components.
- `/components`: React UI components (chat-input, interface, message container, project overview).
- `/components/ui`: shared UI primitives (button, drawer, input, label, resizable, switch).
- `/lib/ai/search.ts`: helper to query Azure Cognitive Search.
- `/lib/env.mjs` & `/lib/utils.ts`: environment variable loader and utilities.

##### Key Architecture Details from README
- Retrieval: uses `lib/ai/search.ts` to fetch top-k embeddings from Azure Cognitive Search.
- Chat generation: uses the Vercel AI SDK’s `streamText` and `useChat` to pipe data between backend and frontend.
- Real-time streaming: backend streams partial tokens back to the client for a typing effect.

##### Components
a. Main Components
- Client Browser (React/Next.js app)
- Next.js Frontend Layer (app directory, UI components)
- Next.js API Layer (`/api/chat/route.ts`)
- Azure Cognitive Search Service
- Azure OpenAI Service
- Environment & Config (Vercel AI SDK, .env variables)
b. Relationships and Data Flow
1. User in Browser types a message → triggers `useChat` hook.
2. Frontend calls the API route `/api/chat`.
3. API route:
– Loads embeddings and search parameters from environment.
– Calls Azure Cognitive Search to retrieve relevant documents/vectors.
– Constructs RAG prompt and calls Azure OpenAI to generate chat.
– Streams the AI response back to the frontend via Vercel `streamText`.
4. Frontend receives streaming tokens and updates the chat UI.
c. Architectural Patterns
- Serverless Functions: API route as ephemeral serverless endpoint.
- RAG Pattern: combine vector search results with LLM prompt.
- Streaming Data Flow: chunked responses for real-time UI updates.
d. Technologies & Frameworks
- Next.js 13 (App Router)
- Vercel AI SDK (`useChat`, `streamText`)
- Azure Cognitive Search (vector search, semantic config)
- Azure OpenAI (chat and embedding models)
- React, Tailwind CSS, Framer Motion

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Browser"
        Browser["Client Browser"]:::frontend
    end

    subgraph "Frontend Layer"
        AppRouter["layout.tsx"]:::frontend
        HomePage["page.tsx"]:::frontend
        Globals["globals.css"]:::frontend
        ChatInterface["Chat Interface"]:::frontend
        ChatInput["Chat Input"]:::frontend
        MessageContainer["Message Container"]:::frontend
        ProjectOverview["Project Overview"]:::frontend
        subgraph "UI Primitives"
            Button["Button"]:::frontend
            Drawer["Drawer"]:::frontend
            InputUI["Input"]:::frontend
            Label["Label"]:::frontend
            Resizable["Resizable"]:::frontend
            Switch["Switch"]:::frontend
        end
    end

    subgraph "Backend Layer"
        API["Serverless API Route<br>/api/chat/route.ts"]:::backend
        SearchLib["Azure Cognitive Search Helper<br>lib/ai/search.ts"]:::backend
        subgraph "Config & Utils"
            Env["Environment Loader<br>lib/env.mjs"]:::config
            Utils["Utility Functions<br>lib/utils.ts"]:::config
            NextConfig["Next.js Config<br>next.config.mjs"]:::config
            DotEnv["Env Example<br>.env.example"]:::config
        end
    end

    subgraph "External Services"
        CogSearch[(Azure Cognitive Search)]:::external
        OpenAI(("Azure OpenAI")):::external
    end

    Browser --> AppRouter
    AppRouter --> HomePage
    HomePage --> Globals
    HomePage --> ChatInterface
    ChatInterface --> ChatInput
    ChatInterface --> MessageContainer
    ChatInterface --> ProjectOverview
    ChatInterface -->|"useChat"| API
    API --> Env
    API --> Utils
    API --> NextConfig
    API --> DotEnv
    API --> SearchLib
    SearchLib --> CogSearch
    CogSearch --> SearchLib
    API -->|"prompt assembly"| OpenAI
    OpenAI -->|"streamText"| ChatInterface

    click AppRouter "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/app/(preview)/layout.tsx"
    click HomePage "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/app/(preview)/page.tsx"
    click Globals "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/app/(preview)/globals.css"
    click ChatInput "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/chat-input.tsx"
    click ChatInterface "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/chat-interface.tsx"
    click MessageContainer "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/message-container.tsx"
    click ProjectOverview "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/project-overview.tsx"
    click Button "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/ui/button.tsx"
    click Drawer "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/ui/drawer.tsx"
    click InputUI "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/ui/input.tsx"
    click Label "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/ui/label.tsx"
    click Resizable "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/ui/resizable.tsx"
    click Switch "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/components/ui/switch.tsx"
    click API "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/app/(preview)/api/chat/route.ts"
    click SearchLib "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/lib/ai/search.ts"
    click Env "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/lib/env.mjs"
    click Utils "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/lib/utils.ts"
    click NextConfig "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/next.config.mjs"
    click DotEnv "https://github.com/azure-samples/azure-ai-vercel-rag-starter/blob/main/.env.example"

    classDef frontend fill:#bfdbfe,stroke:#1e40af,color:#1e3a8a
    classDef backend fill:#bbf7d0,stroke:#166534,color:#14532d
    classDef external fill:#fed7aa,stroke:#b45309,color:#7c2d12
    classDef config fill:#e5e7eb,stroke:#6b7280,color:#374151
```
