# bunsdev/perplexica-search-engine-ai architecture

> Architecture diagram of the GitHub repository bunsdev/perplexica-search-engine-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bunsdev/perplexica-search-engine-ai
- Repository: https://github.com/bunsdev/perplexica-search-engine-ai

## Overview

Vane is a privacy-focused AI answering engine: users configure models and search preferences, ask questions, and receive streamed answers with cited sources, suggestions, and contextual widgets. Chat requests load configured models and hand research to a search agent; search mode also has a separate API agent. The graph preserves documented discovery, media search, uploads, history, and provider configuration. Some subsystem paths and links are based on the README or SOURCE INDEX rather than inspected implementations; dashed links mark unverified integration.

Main entry points: [`src/app/api/chat/route.ts`](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/api/chat/route.ts) (Chat endpoint), [`src/lib/agents/search/index.ts`](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/agents/search/index.ts) (Search agent), [`src/lib/uploads/manager.ts`](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/uploads/manager.ts) (Upload processing), [`src/lib/models/registry.ts`](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/models/registry.ts) (Model registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_chat_ui["Chat interface<br/>[ChatWindow.tsx]"]
  node_chat_state["Chat state<br/>[useChat.tsx]"]
  node_discovery_ui["Discover and library<br/>[page.tsx]"]
  node_settings_ui["Settings and setup<br/>[SettingsField.tsx]"]
end

subgraph group_api["Application API"]
  node_chat_api["Chat endpoint<br/>[route.ts]"]
  node_search_api["Search endpoint<br/>[route.ts]"]
  node_other_api["Feature endpoints<br/>[route.ts]"]
  node_uploads_api["Upload endpoint<br/>[route.ts]"]
end

subgraph group_research["Search and enrichment"]
  node_search_agent["Search agent<br/>[index.ts]"]
  node_api_search_agent["API search agent<br/>[api.ts]"]
  node_researcher["Research actions"]
  node_widgets["Context widgets"]
  node_media_agents["Image and video search<br/>[image.ts]"]
  node_suggestions["Answer suggestions<br/>[index.ts]"]
  node_searxng["SearxNG search<br/>[searxng.ts]"]
end

subgraph group_models["Models and configuration"]
  node_model_registry["Model registry<br/>[registry.ts]"]
  node_provider_adapters["Provider adapters<br/>[index.ts]"]
  node_llm_base["LLM interface<br/>[llm.ts]"]
  node_config["Provider configuration<br/>[index.ts]"]
  node_embedding["Embedding interface<br/>[embedding.ts]"]
end

subgraph group_data["Persistence and files"]
  node_db[("Chat database<br/>[schema.ts]")]
  node_session["Live sessions<br/>[session.ts]"]
  node_upload_manager["Upload processing<br/>[manager.ts]"]
  node_text_splitter["Text chunking<br/>[splitText.ts]"]
  node_upload_store[("Upload files<br/>[store.ts]")]
end

node_user(("User"))

node_user -->|"asks questions"| node_chat_ui
node_user -->|"configures models"| node_settings_ui
node_user -->|"browses content"| node_discovery_ui
node_chat_ui -->|"uses state"| node_chat_state
node_chat_api -->|"loads models"| node_model_registry
node_chat_api -->|"starts research"| node_search_agent
node_chat_api -->|"creates session"| node_session
node_chat_api -->|"checks chat"| node_db
node_search_api -->|"loads models"| node_model_registry
node_search_api -->|"starts search"| node_api_search_agent
node_search_agent -->|"runs research"| node_researcher
node_search_agent -->|"uses widgets"| node_widgets
node_search_agent -->|"uses chat data"| node_db
node_api_search_agent -->|"runs research"| node_researcher
node_model_registry -->|"selects adapters"| node_provider_adapters
node_model_registry -->|"reads configuration"| node_config
node_provider_adapters -.->|"implements interface"| node_llm_base
node_other_api -->|"fetches discovery"| node_searxng
node_media_agents -->|"searches media"| node_searxng
node_other_api -.->|"dispatches media search"| node_media_agents
node_chat_state -.->|"requests suggestions"| node_suggestions
node_uploads_api -->|"processes uploads"| node_upload_manager
node_upload_manager -->|"chunks text"| node_text_splitter
node_upload_manager -->|"embeds chunks"| node_embedding
node_upload_manager -.->|"stores files"| node_upload_store
node_researcher -.->|"searches web"| node_searxng
node_settings_ui -.->|"updates settings"| node_config

click node_chat_ui "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/components/ChatWindow.tsx"
click node_chat_state "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/hooks/useChat.tsx"
click node_discovery_ui "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/discover/page.tsx"
click node_settings_ui "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/components/Settings/SettingsField.tsx"
click node_chat_api "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/api/chat/route.ts"
click node_search_api "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/api/search/route.ts"
click node_other_api "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/api/discover/route.ts"
click node_search_agent "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/agents/search/index.ts"
click node_api_search_agent "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/agents/search/api.ts"
click node_researcher "https://github.com/bunsdev/perplexica-search-engine-ai/tree/master/src/lib/agents/search/researcher"
click node_widgets "https://github.com/bunsdev/perplexica-search-engine-ai/tree/master/src/lib/agents/search/widgets"
click node_media_agents "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/agents/media/image.ts"
click node_suggestions "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/agents/suggestions/index.ts"
click node_searxng "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/searxng.ts"
click node_model_registry "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/models/registry.ts"
click node_provider_adapters "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/models/providers/index.ts"
click node_llm_base "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/models/base/llm.ts"
click node_config "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/config/index.ts"
click node_db "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/db/schema.ts"
click node_session "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/session.ts"
click node_uploads_api "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/api/uploads/route.ts"
click node_upload_manager "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/uploads/manager.ts"
click node_text_splitter "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/utils/splitText.ts"
click node_embedding "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/models/base/embedding.ts"
click node_upload_store "https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/uploads/store.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat_ui,node_chat_state,node_discovery_ui,node_settings_ui,node_user toneBlue
class node_chat_api,node_search_api,node_other_api,node_uploads_api toneAmber
class node_search_agent,node_api_search_agent,node_researcher,node_widgets,node_media_agents,node_suggestions,node_searxng toneMint
class node_model_registry,node_provider_adapters,node_llm_base,node_config,node_embedding toneRose
class node_db,node_session,node_upload_manager,node_text_splitter,node_upload_store toneIndigo
```

## Components

### User experience

- [Chat interface](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/components/ChatWindow.tsx): `src/components/ChatWindow.tsx`
- [Chat state](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/hooks/useChat.tsx): `src/lib/hooks/useChat.tsx`
- [Discover and library](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/discover/page.tsx): `src/app/discover/page.tsx`
- [Settings and setup](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/components/Settings/SettingsField.tsx): `src/components/Settings/SettingsField.tsx`

### Application API

- [Chat endpoint](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Search endpoint](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/api/search/route.ts): `src/app/api/search/route.ts`
- [Feature endpoints](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/api/discover/route.ts): `src/app/api/discover/route.ts`
- [Upload endpoint](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/app/api/uploads/route.ts): `src/app/api/uploads/route.ts`

### Search and enrichment

- [Search agent](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/agents/search/index.ts): `src/lib/agents/search/index.ts`
- [API search agent](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/agents/search/api.ts): `src/lib/agents/search/api.ts`
- [Research actions](https://github.com/bunsdev/perplexica-search-engine-ai/tree/master/src/lib/agents/search/researcher): `src/lib/agents/search/researcher`
- [Context widgets](https://github.com/bunsdev/perplexica-search-engine-ai/tree/master/src/lib/agents/search/widgets): `src/lib/agents/search/widgets`
- [Image and video search](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/agents/media/image.ts): `src/lib/agents/media/image.ts`
- [Answer suggestions](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/agents/suggestions/index.ts): `src/lib/agents/suggestions/index.ts`
- [SearxNG search](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/searxng.ts): `src/lib/searxng.ts`

### Models and configuration

- [Model registry](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/models/registry.ts): `src/lib/models/registry.ts`
- [Provider adapters](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/models/providers/index.ts): `src/lib/models/providers/index.ts`
- [LLM interface](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/models/base/llm.ts): `src/lib/models/base/llm.ts`
- [Provider configuration](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/config/index.ts): `src/lib/config/index.ts`
- [Embedding interface](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/models/base/embedding.ts): `src/lib/models/base/embedding.ts`

### Persistence and files

- [Chat database](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/db/schema.ts): `src/lib/db/schema.ts`
- [Live sessions](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/session.ts): `src/lib/session.ts`
- [Upload processing](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/uploads/manager.ts): `src/lib/uploads/manager.ts`
- [Text chunking](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/utils/splitText.ts): `src/lib/utils/splitText.ts`
- [Upload files](https://github.com/bunsdev/perplexica-search-engine-ai/blob/master/src/lib/uploads/store.ts): `src/lib/uploads/store.ts`

### Other components

- **User**

## Connections

- User → Chat interface: asks questions (evidence: `README.md`)
- User → Settings and setup: configures models (evidence: `README.md`)
- User → Discover and library: browses content (evidence: `README.md`)
- Chat interface → Chat state: uses state (evidence: `src/components/ChatWindow.tsx`)
- Chat endpoint → Model registry: loads models (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → Search agent: starts research (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → Live sessions: creates session (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → Chat database: checks chat (evidence: `src/app/api/chat/route.ts`)
- Search endpoint → Model registry: loads models (evidence: `src/app/api/search/route.ts`)
- Search endpoint → API search agent: starts search (evidence: `src/app/api/search/route.ts`)
- Search agent → Research actions: runs research (evidence: `src/lib/agents/search/index.ts`)
- Search agent → Context widgets: uses widgets (evidence: `src/lib/agents/search/index.ts`)
- Search agent → Chat database: uses chat data (evidence: `src/lib/agents/search/index.ts`)
- API search agent → Research actions: runs research (evidence: `src/lib/agents/search/api.ts`)
- Model registry → Provider adapters: selects adapters (evidence: `src/lib/models/registry.ts`)
- Model registry → Provider configuration: reads configuration (evidence: `src/lib/models/registry.ts`)
- Provider adapters → LLM interface: implements interface
- Feature endpoints → SearxNG search: fetches discovery (evidence: `src/app/api/discover/route.ts`)
- Image and video search → SearxNG search: searches media (evidence: `src/lib/agents/media/image.ts`)
- Feature endpoints → Image and video search: dispatches media search
- Chat state → Answer suggestions: requests suggestions
- Upload endpoint → Upload processing: processes uploads (evidence: `src/app/api/uploads/route.ts`)
- Upload processing → Text chunking: chunks text (evidence: `src/lib/uploads/manager.ts`)
- Upload processing → Embedding interface: embeds chunks (evidence: `src/lib/uploads/manager.ts`)
- Upload processing → Upload files: stores files
- Research actions → SearxNG search: searches web
- Settings and setup → Provider configuration: updates settings
