# Where to Find Vane's Architecture Documentation: Complete Developer Guide

> Find Vane's architecture documentation in the ItzCrazyKns/Vane repository docs directory. Access READMEmd for overviews and WORKINGmd for detailed request flows. Your complete developer guide.

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

---

**Vane's architecture documentation is located in the `docs/architecture` directory of the ItzCrazyKns/Vane repository, containing [`README.md`](https://github.com/ItzCrazyKns/Vane/blob/main/README.md) for high-level component overviews and [`WORKING.md`](https://github.com/ItzCrazyKns/Vane/blob/main/WORKING.md) for detailed request processing flows.**

The ItzCrazyKns/Vane project is a Next.js-based AI search platform that orchestrates multiple LLM providers, embeddings, and meta-search capabilities. Understanding **Vane's architecture documentation** enables developers to trace how user queries flow from the React frontend through classification agents to streaming responses, and to locate extension points for custom models or widgets.

## Locating Vane's Architecture Documentation

The canonical documentation resides in two dedicated files within the repository:

- **[`docs/architecture/README.md`](https://github.com/ItzCrazyKns/Vane/blob/main/docs/architecture/README.md)** – Provides a concise high-level overview of system components, including the UI layer, API routes, agent orchestration, and storage mechanisms.
- **[`docs/architecture/WORKING.md`](https://github.com/ItzCrazyKns/Vane/blob/main/docs/architecture/WORKING.md)** – Details the step-by-step execution flow of a user query, covering classification, parallel research and widget execution, answer generation, and citation handling.

Together, these documents provide a complete blueprint of Vane's design from the Next.js interface down to the database layer.

## High-Level System Components

Vane's architecture follows a modular design pattern with clear separation between presentation, orchestration, and infrastructure layers.

### User Interface

The **UI layer** handles chat interactions, search inputs, and citation displays. Key implementations include:

- [`src/app/page.tsx`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/page.tsx) – The main entry point for the Next.js application.
- `src/components/MessageRenderer/*` – React components responsible for rendering message streams and citations.

### API Routes

**HTTP endpoints** power both the web interface and external integrations:

- [`src/app/api/chat/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chat/route.ts) – Core streaming endpoint for chat completions.
- [`src/app/api/search/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/search/route.ts) – Handles web search queries via SearxNG.
- [`src/app/api/providers/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/providers/route.ts) – Exposes available LLM and embedding providers.

### Agents and Orchestration

The **agent layer** classifies queries, executes parallel research, and assembles final answers:

- [`src/lib/agents/search/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/index.ts) – Central orchestrator coordinating the entire search pipeline.
- [`src/lib/agents/search/classifier.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/classifier.ts) – Determines query type and routing strategy.
- `src/lib/agents/search/widgets/*` – Specialized tools for specific tasks like weather or calculations.

### Search and Model Backend

**Infrastructure components** handle external search and AI model interactions:

- [`src/lib/searxng.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/searxng.ts) – Wrapper for the SearxNG meta-search engine.
- [`src/lib/models/registry.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/registry.ts) – Central registry for loading LLM and embedding providers.
- `src/lib/models/providers/*` – Provider-specific implementations (OpenAI, Ollama, Anthropic, Gemini, Groq, Lemonade).
- [`src/lib/models/providers/openai/openaiLLM.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/openai/openaiLLM.ts) and [`src/lib/models/providers/ollama/ollamaLLM.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/ollama/ollamaLLM.ts) – Concrete LLM implementations.
- [`src/lib/models/providers/openai/openaiEmbedding.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/openai/openaiEmbedding.ts) and [`src/lib/models/providers/ollama/ollamaEmbedding.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/providers/ollama/ollamaEmbedding.ts) – Embedding model implementations.

### Data Persistence

**Storage layer** manages state via Drizzle ORM:

- [`src/lib/db/schema.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/db/schema.ts) – Database schema definitions for chats, messages, and file uploads.
- [`src/lib/db/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/db/index.ts) – Database connection and query interface.
- [`src/lib/session.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/session.ts) – Manages streaming event sessions between server and client.

## End-to-End Request Flow

According to [`WORKING.md`](https://github.com/ItzCrazyKns/Vane/blob/main/WORKING.md), a typical query executes through four distinct phases:

1. **Classification** – The system analyzes the incoming query in [`src/lib/agents/search/classifier.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/classifier.ts) to determine required capabilities.
2. **Parallel Execution** – Research agents and widgets run simultaneously, with widgets located in `src/lib/agents/search/widgets/*` handling specialized data retrieval.
3. **Answer Generation** – Results are synthesized using the configured LLM provider from [`src/lib/models/registry.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/registry.ts).
4. **Citation Assembly** – Sources are formatted and attached to the streaming response via the session manager in [`src/lib/session.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/session.ts).

## Implementation Examples

### Calling the Chat API Endpoint

Interact with Vane's chat system programmatically via the streaming endpoint:

```typescript
const response = await fetch('http://localhost:3000/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: {
      messageId: 'msg-1',
      chatId: 'chat-123',
      content: 'What is the weather in Berlin?'
    },
    optimizationMode: 'balanced',
    sources: [],
    history: [],
    files: [],
    chatModel: { providerId: 'openai', key: 'my-openai-key' },
    embeddingModel: { providerId: 'openai', key: 'my-openai-key' },
    systemInstructions: null
  })
});

const reader = response.body?.getReader();
while (true) {
  const { value, done } = await reader?.read() ?? { done: true };
  if (done) break;
  console.log(new TextDecoder().decode(value));
}

```

*(The endpoint streams JSON lines containing blocks, updates, or `messageEnd` events. See [`src/app/api/chat/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chat/route.ts) for the server-side implementation.)*

### Loading Models via the Registry

Abstract over multiple providers using the central registry:

```typescript
import ModelRegistry from '@/lib/models/registry';

async function loadModels() {
  const registry = new ModelRegistry();

  // Load the chat LLM (e.g., OpenAI's gpt-4o)
  const llm = await registry.loadChatModel('openai', 'my-openai-key');

  // Load the embedding model (e.g., OpenAI text-embedding-ada-002)
  const embedding = await registry.loadEmbeddingModel('openai', 'my-openai-key');

  return { llm, embedding };
}

```

*The registry abstracts over provider implementations located under `src/lib/models/providers/*`.*

### Executing Research Widgets

Manually trigger specific research widgets for targeted data retrieval:

```typescript
import WeatherWidget from '@/lib/agents/search/widgets/weatherWidget';
import SessionManager from '@/lib/session';

async function runWeatherWidget(city: string) {
  const session = SessionManager.createSession();
  const widget = new WeatherWidget();

  // Subscribe to widget events (data, end, error)
  const unsubscribe = session.subscribe((event, data) => {
    if (event === 'data') console.log('Widget data:', data);
    if (event === 'end') console.log('Widget finished');
  });

  await widget.run(session, { city });
  unsubscribe();
}

```

*Widgets implement a `run(session, params)` contract and push updates through the same streaming channel used by the main chat agent.*

## Critical Source Files Reference

| File | Purpose |
|------|---------|
| [`docs/architecture/README.md`](https://github.com/ItzCrazyKns/Vane/blob/main/docs/architecture/README.md) | Component overview and system design |
| [`docs/architecture/WORKING.md`](https://github.com/ItzCrazyKns/Vane/blob/main/docs/architecture/WORKING.md) | Detailed request processing flow |
| [`src/app/api/chat/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chat/route.ts) | Chat endpoint with streaming implementation |
| [`src/lib/agents/search/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/index.ts) | Main search orchestration logic |
| [`src/lib/models/registry.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/registry.ts) | Provider loading and management |
| [`src/lib/session.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/session.ts) | Server-client streaming session management |
| [`src/lib/db/schema.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/db/schema.ts) | Database schema definitions |
| [`src/lib/searxng.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/searxng.ts) | Meta-search backend integration |

## Summary

- **Vane's architecture documentation** is centralized in [`docs/architecture/README.md`](https://github.com/ItzCrazyKns/Vane/blob/main/docs/architecture/README.md) (components) and [`WORKING.md`](https://github.com/ItzCrazyKns/Vane/blob/main/WORKING.md) (flow).
- The system uses a **Next.js frontend** ([`src/app/page.tsx`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/page.tsx)) communicating with **API routes** ([`src/app/api/chat/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chat/route.ts)).
- **Agent orchestration** happens in [`src/lib/agents/search/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/index.ts), with classification in [`classifier.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/classifier.ts) and tools in `widgets/*`.
- **Model abstraction** is handled by [`src/lib/models/registry.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/registry.ts), supporting multiple providers via `src/lib/models/providers/*`.
- **Data persistence** uses Drizzle ORM defined in [`src/lib/db/schema.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/db/schema.ts), while **streaming** is managed by [`src/lib/session.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/session.ts).

## Frequently Asked Questions

### Where is the high-level overview of Vane's system design?

The high-level overview documenting Vane's main components—including the UI, API routes, agents, search backend, LLMs, embeddings, and storage—is located at [`docs/architecture/README.md`](https://github.com/ItzCrazyKns/Vane/blob/main/docs/architecture/README.md) in the repository root.

### How does Vane process a user query from start to finish?

According to [`WORKING.md`](https://github.com/ItzCrazyKns/Vane/blob/main/WORKING.md), queries flow through classification ([`src/lib/agents/search/classifier.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/agents/search/classifier.ts)), parallel research and widget execution, answer generation using the model registry ([`src/lib/models/registry.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/registry.ts)), and finally citation assembly before streaming to the client via [`src/lib/session.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/session.ts).

### Which file handles the streaming chat API?

The chat endpoint implementation that handles streaming JSON lines to the client is found in [`src/app/api/chat/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chat/route.ts), which orchestrates calls to the agent layer and manages the response stream.

### How do I add support for a new LLM provider?

New providers are added under `src/lib/models/providers/` following the pattern established in [`openai/openaiLLM.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/openai/openaiLLM.ts) or [`ollama/ollamaLLM.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/ollama/ollamaLLM.ts), then registered in [`src/lib/models/registry.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/models/registry.ts) to make them available to the chat API.