# langchain-ai/langchain-nextjs-template architecture

> Architecture diagram of the GitHub repository langchain-ai/langchain-nextjs-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langchain-ai/langchain-nextjs-template
- Repository: https://github.com/langchain-ai/langchain-nextjs-template

## Overview

##### Project type and purpose
- This is a full-stack Next.js 13 application (using the App Router) that demonstrates several LangChain.js use cases (simple chat, structured output, agents, RAG) via serverless Edge API routes. It uses Vercel’s AI SDK for streaming token output, Supabase (or any vector store) for retrieval, SERPAPI for agent web searches, and LangGraph.js for agent workflows.

##### File structure
- Top-level:
- Configuration: .env.example, next.config.js, tsconfig.json, ESLint/Prettier configs
- “app/”: Next.js App Router folder containing:
– “page.tsx” (landing) plus subfolders for each UI route (chat, structured_output, agents, retrieval, retrieval_agents, ai_sdk, langgraph)
– “api/”: each folder under app/api (chat, chat/agents, chat/retrieval, etc.) exports a serverless route.ts handler
- “components/”: React UI components (ChatWindow, MessageBubble, form, Navbar, etc.) and a “ui/” subfolder for primitives (button, input, dialog)
- “data/”: default text to ingest
- “utils/”: shared helpers (e.g. cn.ts)
- “public/”: static assets (images, videos)

##### Key insights from README
- Demonstrates multiple LLM patterns:
- Simple chat (app/api/chat)
- Structured JSON output via Zod + OpenAI Functions
- Agents via LangGraph.js (SERPAPI integration)
- Retrieval-augmented generation (RAG) chains using Supabase vector store
- Streams everything back via Vercel AI SDK on Edge
- Encourages swapping in other vectorstores or custom LangGraph graphs

##### Main components
a. Frontend (Next.js App Router + React UI)
- Pages: /chat, /structured_output, /agents, /retrieval, /retrieval_agents, /ai_sdk, /langgraph
- Shared UI layer: components/ui, components/…
- Vercel AI SDK client stream handler
b. Backend (Next.js Edge API routes)
- app/api/chat/route.ts (and sub-routes: structured_output, agents, retrieval, retrieval_agents)
- Ingest API: app/api/retrieval/ingest/route.ts
- Each route spins up a LangChain chain or LangGraph agent workflow
c. LangChain & LangGraph modules
- Chains and tools orchestrated in route handlers
- Zod schemas for structured output
- LangGraph agent graphs under app/langgraph/agent
d. External services
- OpenAI API (LLM calls, streaming)
- Supabase vector store (embeddings storage & retrieval)
- SERPAPI (agent web search)
- (Optional) LangSmith tracing if enabled
e. Data store
- Supabase (documents table)

##### Relationships & data flow
1. User interacts with Next.js page → clicks “Send” or “Upload”
2. Frontend calls the corresponding /api/* Edge route over HTTP (fetch)
3. Edge function:
- For chat/structured_output: builds a LangChain chain with prompts & Zod, calls OpenAI, streams back
- For agents: loads a LangGraph graph, executes steps (web search via SERPAPI, etc.), streams back
- For retrieval: (a) ingest route splits & embeds data, writes to Supabase; (b) retrieval route queries Supabase, builds chain, calls LLM
4. Streaming responses from Edge function → Vercel AI SDK client → React UI renders bubbles
5. Supabase persists embeddings; SERPAPI returns search results on demand

##### Architectural patterns & design principles
- Folder-based routing & Server Components (Next.js App Router)
- Serverless Edge functions for each API route
- Streaming architecture via AI SDK (bidirectional, token-by-token)
- Modular chains & agents (LangChain, LangGraph) for separation of concerns
- Pluggable vector store integration

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Client (Browser/Next.js Frontend)"
    direction TB
    LP["Landing Page"]:::frontend
    CP["Chat Page (UI)"]:::frontend
    SOP["Structured Output Page"]:::frontend
    AP["Agent Page"]:::frontend
    RP["Retrieval Page"]:::frontend
    RAP["Retrieval Agents Page"]:::frontend
    AIMP["AI SDK Main Page"]:::frontend
    AISAP["AI SDK Agent Page"]:::frontend
    AISTP["AI SDK Tools Page"]:::frontend
    LGP["LangGraph Page"]:::frontend

    CW["Chat Window"]:::frontend
    CMB["Chat Message Bubble"]:::frontend
    UDF["Upload Documents Form"]:::frontend
    UIP["UI Primitives"]:::frontend
    STY["Global Styles"]:::frontend
    UTIL["Utility Helpers"]:::frontend
  end

  subgraph "Serverless Edge API"
    direction TB
    subgraph "Chat API"
      direction TB
      CA1["Chat API"]:::server
      CA2["Structured Output API"]:::server
      CA3["Chat Agents API"]:::server
      CA4["Chat Retrieval API"]:::server
      CA5["Chat Retrieval Agents API"]:::server
    end
    RI["Retrieval Ingest API"]:::server
  end

  subgraph "AI Orchestration"
    direction TB
    LG_AGENT["LangGraph Agent Definition"]:::orchestration
    LG_CFG["LangGraph Workflow Config"]:::orchestration
  end

  subgraph "External Services / Data Store"
    direction TB
    OA["OpenAI API"]:::external
    SB["Supabase Vector Store"]:::external
    SP["SERPAPI"]:::external
  end

  LP -->|User interaction| CP
  LP -->|User interaction| SOP
  LP -->|User interaction| AP
  LP -->|User interaction| RP
  LP -->|User interaction| RAP
  LP -->|User interaction| AIMP
  LP -->|User interaction| LGP

  CP -->|fetch| CA1
  SOP -->|fetch| CA2
  AP -->|fetch| CA3
  RP -->|fetch| CA4
  RAP -->|fetch| CA5
  RP -->|fetch| RI
  AIMP -->|fetch| CA1
  AISAP -->|fetch| CA3
  AISTP -->|fetch| CA3
  LGP -->|fetch| CA3

  CA1 -->|"invoke chain"| LG_AGENT
  CA2 -->|"invoke chain"| LG_AGENT
  CA3 -->|"execute graph"| LG_AGENT
  CA4 -->|"invoke chain"| LG_AGENT
  CA5 -->|"execute graph"| LG_AGENT
  RI -->|"ingest & embed"| SB

  LG_AGENT -->|"LLM call (stream)"| OA
  LG_AGENT -->|"web search"| SP
  LG_AGENT -->|"query embeddings"| SB

  OA -->|"stream tokens"| CP
  OA -->|"stream tokens"| SOP
  OA -->|"stream tokens"| AP
  OA -->|"stream tokens"| RP
  OA -->|"stream tokens"| RAP
  OA -->|"stream tokens"| AIMP
  OA -->|"stream tokens"| AISAP
  OA -->|"stream tokens"| AISTP
  OA -->|"stream tokens"| LGP

  SB -->|"return docs"| LG_AGENT

  click LP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/page.tsx"
  click CP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/agents/page.tsx"
  click SOP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/structured_output/page.tsx"
  click AP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/agents/page.tsx"
  click RP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/retrieval/page.tsx"
  click RAP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/retrieval_agents/page.tsx"
  click AIMP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/page.tsx"
  click AISAP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/agent/page.tsx"
  click AISTP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/tools/page.tsx"
  click LGP "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/langgraph/page.tsx"

  click CA1 "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/api/chat/route.ts"
  click CA2 "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/api/chat/structured_output/route.ts"
  click CA3 "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/api/chat/agents/route.ts"
  click CA4 "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/api/chat/retrieval/route.ts"
  click CA5 "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/api/chat/retrieval_agents/route.ts"
  click RI "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/api/retrieval/ingest/route.ts"

  click LG_AGENT "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/langgraph/agent/agent.ts"
  click LG_CFG "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/langgraph/agent/langgraph.json"

  click CW "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/components/ChatWindow.tsx"
  click CMB "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/components/ChatMessageBubble.tsx"
  click UDF "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/components/UploadDocumentsForm.tsx"
  click UIP "https://github.com/langchain-ai/langchain-nextjs-template/tree/main/components/ui"
  click STY "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/globals.css"
  click UTIL "https://github.com/langchain-ai/langchain-nextjs-template/blob/main/utils/cn.ts"

  classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
  classDef server fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
  classDef orchestration fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00
  classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
```
