# What Are the Seven Key Components of Vane's Architecture?

> Explore Vane's architecture. Discover the seven essential components including UI, API, Agents, Search, LLMs, Embedding Models, and Storage. Learn how these TypeScript modules power Vane's functionality.

- Repository: [Kushagra Srivastava/Vane](https://github.com/ItzCrazyKns/Vane)
- Tags: architecture
- Published: 2026-03-11

---

**Vane's architecture consists of seven core components: User Interface, API Routes, Agents & Orchestration, Search Backend, LLMs, Embedding Models, and Storage, each implemented in dedicated TypeScript modules under `src/`.**

The open-source project **ItzCrazyKns/Vane** delivers an AI-driven chat and search experience through a modular, Next.js-based codebase. Understanding the seven key components of Vane's architecture is essential for developers extending its capabilities or deploying custom instances. Each component occupies a specific directory within the repository and manages a distinct phase of the request lifecycle, from frontend interaction to persistent storage.

## 1. User Interface

The **User Interface** serves as the web-based frontend where users submit queries, view streaming responses, and interact with research widgets. Built with Next.js App Router conventions, this component renders the main chat window and handles real-time message display.

**Primary source files:** [`src/app/page.tsx`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/page.tsx), [`src/components/ChatWindow.tsx`](https://github.com/ItzCrazyKns/Vane/blob/main/src/components/ChatWindow.tsx)

The entry point exports a simple page component that mounts the chat interface:

```tsx
import ChatWindow from '@/components/ChatWindow';

export default function Home() {
  return <ChatWindow />;
}

```

## 2. API Routes

**API Routes** provide the server-side endpoints that bridge the frontend and backend logic. These routes handle POST requests from the UI, validate payloads, and forward them to the orchestration layer.

**Primary source file:** [`src/app/api/chat/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chat/route.ts)

The main chat endpoint accepts message history and initiates the workflow:

```ts
// src/app/api/chat/route.ts
export async function POST(req: Request) {
  const { messages } = await req.json();
  // forward to the orchestrator
  const answer = await runChatWorkflow(messages);
  return Response.json(answer);
}

```

## 3. Agents & Orchestration

The **Agents & Orchestration** layer acts as the central nervous system of Vane. It classifies incoming queries, determines whether to activate research mode or widgets, executes these operations in parallel, and assembles the final response with proper citations.

**Primary source file:** [`src/lib/agents/search/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/index.ts)

This component uses an LLM-based classifier to analyze intent before deciding on the execution path:

```ts
// src/lib/agents/search/index.ts
const classification = await classifier.classify(question);
if (classification.needsResearch) {
  const results = await searchSearxng(question);
  // … combine with LLM response
}

```

## 4. Search Backend

The **Search Backend** integrates SearXNG as a meta-search layer, fetching relevant web results when research mode is enabled. This component abstracts the external search API and normalizes results for consumption by the LLM.

**Primary source file:** [`src/lib/searxng.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/searxng.ts)

Developers can invoke searches programmatically:

```ts
import { searchSearxng } from '@/lib/searxng';

const { results, suggestions } = await searchSearxng('latest AI news');

```

## 5. LLMs (Large Language Models)

**LLMs** provide the language-model services for query classification, answer generation, and citation formatting. The architecture abstracts provider-specific implementations behind a common interface, with OpenAI serving as the default provider.

**Primary source file:** [`src/lib/models/providers/openai/openaiLLM.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/openai/openaiLLM.ts)

The LLM class exposes a unified generation method:

```ts
import { OpenAILLM } from '@/lib/models/providers/openai/openaiLLM';

const llm = new OpenAILLM();
const answer = await llm.generate({
  prompt: `Answer the question: ${question}`,
});

```

## 6. Embedding Models

**Embedding Models** generate vector representations of user-uploaded files, enabling **Retrieval-Augmented Generation (RAG)** for semantic similarity search over personal data. This component transforms text chunks into high-dimensional vectors for storage and retrieval.

**Primary source file:** [`src/lib/models/providers/openai/openaiEmbedding.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/openai/openaiEmbedding.ts)

The embedding workflow involves chunking, vectorization, and database storage:

```ts
import { OpenAIEmbedding } from '@/lib/models/providers/openai/openaiEmbedding';

const embedder = new OpenAIEmbedding();
const vectors = await embedder.embed(textChunks);
await db.saveEmbeddingVectors(vectors);

```

## 7. Storage

The **Storage** layer persists chats, messages, and uploaded files using a database abstraction, ensuring conversations remain reloadable across sessions. This component handles CRUD operations for all long-lived data entities.

**Primary source file:** [`src/lib/db/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/db/index.ts)

Chat persistence follows a straightforward creation pattern:

```ts
import { db } from '@/lib/db';

await db.chat.create({
  userId,
  messages: [...],
});

```

## How the Components Interact

Vane processes user requests through a coordinated pipeline that leverages all seven components:

1. The **User Interface** sends a POST request to **API Routes** at `/api/chat`.
2. The **Agents & Orchestration** layer receives the request and uses the **LLM** (Component 5) to classify intent.
3. If external information is required, the orchestrator triggers the **Search Backend** (Component 4) to fetch web results via SearXNG.
4. The **LLM** generates the answer, potentially enriching it with vector data from **Embedding Models** (Component 6) when users have uploaded files.
5. The fully formed response, including citations, is persisted via **Storage** (Component 7) and returned to the **User Interface** for display.

## Summary

- **Vane's architecture** comprises seven specialized components working in concert to deliver AI chat with search capabilities.
- **User Interface** and **API Routes** handle the presentation and transport layers using Next.js conventions.
- **Agents & Orchestration** manages workflow logic, classification, and parallel execution of research tasks.
- **Search Backend** integrates SearXNG for external information retrieval, while **LLMs** and **Embedding Models** handle generation and semantic search respectively.
- **Storage** provides durable persistence for conversations and user data through a database abstraction layer.

## Frequently Asked Questions

### What is the role of the Agents & Orchestration component in Vane?

The **Agents & Orchestration** component serves as the workflow engine, classifying user queries to determine whether to trigger research mode or widgets. Implemented in [`src/lib/agents/search/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/index.ts), it coordinates parallel execution of search tasks and assembles final responses with citations before returning them to the API layer.

### How does Vane handle external search queries?

Vane delegates external search operations to the **Search Backend** component, which interfaces with SearXNG as a meta-search engine. When the orchestrator determines research is needed, it calls `searchSearxng()` from [`src/lib/searxng.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/searxng.ts) to fetch relevant web results, which are then passed to the LLM for synthesis.

### Can Vane work with different LLM providers?

Yes, the **LLMs** component uses an abstraction layer defined in [`src/lib/models/base/llm.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/base/llm.ts) that allows swapping providers. While the default implementation in [`src/lib/models/providers/openai/openaiLLM.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/openai/openaiLLM.ts) supports OpenAI, the base interface enables integration with other providers by implementing the standard generation methods.

### How is user data persisted in Vane?

The **Storage** component manages persistence through a database abstraction located in [`src/lib/db/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/db/index.ts). It handles creation, retrieval, and updates of chat sessions and messages, ensuring user conversations and uploaded files remain available across browser sessions via the `db.chat.create()` and related methods.