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

Vane's architecture documentation is located in the docs/architecture directory of the ItzCrazyKns/Vane repository, containing README.md for high-level component overviews and 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 – Provides a concise high-level overview of system components, including the UI layer, API routes, agent orchestration, and storage mechanisms.
• 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 – 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 – Core streaming endpoint for chat completions.
• src/app/api/search/route.ts – Handles web search queries via SearxNG.
• 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 – Central orchestrator coordinating the entire search pipeline.
• 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 – Wrapper for the SearxNG meta-search engine.
• 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 and src/lib/models/providers/ollama/ollamaLLM.ts – Concrete LLM implementations.
• src/lib/models/providers/openai/openaiEmbedding.ts and src/lib/models/providers/ollama/ollamaEmbedding.ts – Embedding model implementations.

Data Persistence

Storage layer manages state via Drizzle ORM:

• src/lib/db/schema.ts – Database schema definitions for chats, messages, and file uploads.
• src/lib/db/index.ts – Database connection and query interface.
• src/lib/session.ts – Manages streaming event sessions between server and client.

End-to-End Request Flow

According to 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 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.
4. Citation Assembly – Sources are formatted and attached to the streaming response via the session manager in src/lib/session.ts.

Implementation Examples

Calling the Chat API Endpoint

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

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 for the server-side implementation.)

Loading Models via the Registry

Abstract over multiple providers using the central registry:

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:

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	Component overview and system design
docs/architecture/WORKING.md	Detailed request processing flow
src/app/api/chat/route.ts	Chat endpoint with streaming implementation
src/lib/agents/search/index.ts	Main search orchestration logic
src/lib/models/registry.ts	Provider loading and management
src/lib/session.ts	Server-client streaming session management
src/lib/db/schema.ts	Database schema definitions
src/lib/searxng.ts	Meta-search backend integration

Summary

• Vane's architecture documentation is centralized in docs/architecture/README.md (components) and WORKING.md (flow).
• The system uses a Next.js frontend (src/app/page.tsx) communicating with API routes (src/app/api/chat/route.ts).
• Agent orchestration happens in src/lib/agents/search/index.ts, with classification in classifier.ts and tools in widgets/*.
• Model abstraction is handled by 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, while streaming is managed by 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 in the repository root.

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

According to WORKING.md, queries flow through classification (src/lib/agents/search/classifier.ts), parallel research and widget execution, answer generation using the model registry (src/lib/models/registry.ts), and finally citation assembly before streaming to the client via 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, 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 or ollama/ollamaLLM.ts, then registered in src/lib/models/registry.ts to make them available to the chat API.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}