# ramstorageai/perplexica architecture

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

- Interactive diagram: https://gitdiagram.com/ramstorageai/perplexica
- Repository: https://github.com/ramstorageai/perplexica

## Overview

Perplexica is a self-hosted AI answering engine. A user submits a question in the chat UI; the client sends it to a chat or search API, which loads configured models and runs search/research or media agents. Results stream through session events to the UI as answer blocks, cited sources, and widgets. Separate branches cover uploads, suggestions, Discover, provider setup, and locally saved chat history. The source excerpts establish the main chat/search orchestration; some unsampled routes and subsystems are included from the README and source index, so their internal links are omitted where unverified.

Main entry points: [`src/app/api/chat/route.ts`](https://github.com/ramstorageai/perplexica/blob/master/src/app/api/chat/route.ts) (Chat endpoint), [`src/lib/agents/search/index.ts`](https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/index.ts) (Search agent), [`src/lib/agents/search/api.ts`](https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/api.ts) (API search agent), [`src/lib/agents/search/researcher/index.ts`](https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/researcher/index.ts) (Research agent)

## 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_provider_settings["Provider settings<br/>[ModelProvider.tsx]"]
end

subgraph group_orchestration["Answer orchestration"]
  node_chat_api["Chat endpoint<br/>[route.ts]"]
  node_search_api["Search endpoint<br/>[route.ts]"]
  node_search_agent["Search agent<br/>[index.ts]"]
  node_api_search_agent["API search agent<br/>[api.ts]"]
  node_session["Stream session<br/>[session.ts]"]
end

subgraph group_capabilities["Search capabilities"]
  node_classifier["Query classifier<br/>[classifier.ts]"]
  node_researcher["Research agent<br/>[index.ts]"]
  node_search_actions["Research actions"]
  node_widgets["Answer widgets<br/>[index.ts]"]
  node_searxng["SearxNG search<br/>[searxng.ts]"]
  node_uploads["File processing<br/>[manager.ts]"]
  node_media["Image and video search"]
  node_suggestions["Query suggestions<br/>[index.ts]"]
  node_discover["Discover feed<br/>[route.ts]"]
end

subgraph group_platform["Configuration and persistence"]
  node_models["Model registry<br/>[registry.ts]"]
  node_model_providers["Model providers<br/>[index.ts]"]
  node_config_api["Configuration API<br/>[index.ts]"]
  node_chat_store[("Chat database<br/>[schema.ts]")]
end

node_user(("User"))

node_user -->|"asks questions"| node_chat_ui
node_chat_ui -->|"renders state"| node_chat_state
node_chat_state -.->|"submits chat"| node_chat_api
node_chat_api -->|"loads models"| node_models
node_chat_api -->|"starts research"| node_search_agent
node_chat_api -->|"streams events"| node_session
node_chat_api -->|"persists chat"| node_chat_store
node_search_api -->|"loads models"| node_models
node_search_api -->|"starts search"| node_api_search_agent
node_api_search_agent -->|"classifies query"| node_classifier
node_api_search_agent -->|"runs research"| node_researcher
node_api_search_agent -->|"executes widgets"| node_widgets
node_researcher -.->|"dispatches actions"| node_search_actions
node_search_actions -.->|"searches web"| node_searxng
node_search_agent -->|"classifies query"| node_classifier
node_search_agent -->|"runs research"| node_researcher
node_search_agent -->|"executes widgets"| node_widgets
node_chat_api -->|"processes files"| node_uploads
node_models -->|"creates providers"| node_model_providers
node_provider_settings -.->|"configures providers"| node_config_api
node_user -->|"browses articles"| node_discover
node_discover -->|"fetches content"| node_searxng
node_user -->|"searches media"| node_media
node_user -->|"gets suggestions"| node_suggestions
node_user -->|"uploads files"| node_uploads

click node_chat_ui "https://github.com/ramstorageai/perplexica/blob/master/src/components/ChatWindow.tsx"
click node_chat_state "https://github.com/ramstorageai/perplexica/blob/master/src/lib/hooks/useChat.tsx"
click node_chat_api "https://github.com/ramstorageai/perplexica/blob/master/src/app/api/chat/route.ts"
click node_search_api "https://github.com/ramstorageai/perplexica/blob/master/src/app/api/search/route.ts"
click node_search_agent "https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/index.ts"
click node_api_search_agent "https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/api.ts"
click node_session "https://github.com/ramstorageai/perplexica/blob/master/src/lib/session.ts"
click node_models "https://github.com/ramstorageai/perplexica/blob/master/src/lib/models/registry.ts"
click node_model_providers "https://github.com/ramstorageai/perplexica/blob/master/src/lib/models/providers/index.ts"
click node_classifier "https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/classifier.ts"
click node_researcher "https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/researcher/index.ts"
click node_search_actions "https://github.com/ramstorageai/perplexica/tree/master/src/lib/agents/search/researcher/actions"
click node_widgets "https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/widgets/index.ts"
click node_searxng "https://github.com/ramstorageai/perplexica/blob/master/src/lib/searxng.ts"
click node_uploads "https://github.com/ramstorageai/perplexica/blob/master/src/lib/uploads/manager.ts"
click node_media "https://github.com/ramstorageai/perplexica/tree/master/src/lib/agents/media"
click node_suggestions "https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/suggestions/index.ts"
click node_discover "https://github.com/ramstorageai/perplexica/blob/master/src/app/api/discover/route.ts"
click node_config_api "https://github.com/ramstorageai/perplexica/blob/master/src/lib/config/index.ts"
click node_provider_settings "https://github.com/ramstorageai/perplexica/blob/master/src/components/Settings/Sections/Models/ModelProvider.tsx"
click node_chat_store "https://github.com/ramstorageai/perplexica/blob/master/src/lib/db/schema.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_provider_settings,node_user toneBlue
class node_chat_api,node_search_api,node_search_agent,node_api_search_agent,node_session toneAmber
class node_classifier,node_researcher,node_search_actions,node_widgets,node_searxng,node_uploads,node_media,node_suggestions,node_discover toneMint
class node_models,node_model_providers,node_config_api,node_chat_store toneRose
```

## Components

### User experience

- [Chat interface](https://github.com/ramstorageai/perplexica/blob/master/src/components/ChatWindow.tsx): `src/components/ChatWindow.tsx`
- [Chat state](https://github.com/ramstorageai/perplexica/blob/master/src/lib/hooks/useChat.tsx): `src/lib/hooks/useChat.tsx`
- [Provider settings](https://github.com/ramstorageai/perplexica/blob/master/src/components/Settings/Sections/Models/ModelProvider.tsx): `src/components/Settings/Sections/Models/ModelProvider.tsx`

### Answer orchestration

- [Chat endpoint](https://github.com/ramstorageai/perplexica/blob/master/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Search endpoint](https://github.com/ramstorageai/perplexica/blob/master/src/app/api/search/route.ts): `src/app/api/search/route.ts`
- [Search agent](https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/index.ts): `src/lib/agents/search/index.ts`
- [API search agent](https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/api.ts): `src/lib/agents/search/api.ts`
- [Stream session](https://github.com/ramstorageai/perplexica/blob/master/src/lib/session.ts): `src/lib/session.ts`

### Search capabilities

- [Query classifier](https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/classifier.ts): `src/lib/agents/search/classifier.ts`
- [Research agent](https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/researcher/index.ts): `src/lib/agents/search/researcher/index.ts`
- [Research actions](https://github.com/ramstorageai/perplexica/tree/master/src/lib/agents/search/researcher/actions): `src/lib/agents/search/researcher/actions`
- [Answer widgets](https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/search/widgets/index.ts): `src/lib/agents/search/widgets/index.ts`
- [SearxNG search](https://github.com/ramstorageai/perplexica/blob/master/src/lib/searxng.ts): `src/lib/searxng.ts`
- [File processing](https://github.com/ramstorageai/perplexica/blob/master/src/lib/uploads/manager.ts): `src/lib/uploads/manager.ts`
- [Image and video search](https://github.com/ramstorageai/perplexica/tree/master/src/lib/agents/media): `src/lib/agents/media`
- [Query suggestions](https://github.com/ramstorageai/perplexica/blob/master/src/lib/agents/suggestions/index.ts): `src/lib/agents/suggestions/index.ts`
- [Discover feed](https://github.com/ramstorageai/perplexica/blob/master/src/app/api/discover/route.ts): `src/app/api/discover/route.ts`

### Configuration and persistence

- [Model registry](https://github.com/ramstorageai/perplexica/blob/master/src/lib/models/registry.ts): `src/lib/models/registry.ts`
- [Model providers](https://github.com/ramstorageai/perplexica/blob/master/src/lib/models/providers/index.ts): `src/lib/models/providers/index.ts`
- [Configuration API](https://github.com/ramstorageai/perplexica/blob/master/src/lib/config/index.ts): `src/lib/config/index.ts`
- [Chat database](https://github.com/ramstorageai/perplexica/blob/master/src/lib/db/schema.ts): `src/lib/db/schema.ts`

### Other components

- **User**

## Connections

- User → Chat interface: asks questions
- Chat interface → Chat state: renders state (evidence: `src/components/ChatWindow.tsx`)
- Chat state → Chat endpoint: submits chat
- 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 → Stream session: streams events (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → Chat database: persists 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`)
- API search agent → Query classifier: classifies query (evidence: `src/lib/agents/search/api.ts`)
- API search agent → Research agent: runs research (evidence: `src/lib/agents/search/api.ts`)
- API search agent → Answer widgets: executes widgets (evidence: `src/lib/agents/search/api.ts`)
- Research agent → Research actions: dispatches actions
- Research actions → SearxNG search: searches web
- Search agent → Query classifier: classifies query (evidence: `src/lib/agents/search/index.ts`)
- Search agent → Research agent: runs research (evidence: `src/lib/agents/search/index.ts`)
- Search agent → Answer widgets: executes widgets (evidence: `src/lib/agents/search/index.ts`)
- Chat endpoint → File processing: processes files (evidence: `src/app/api/chat/route.ts`)
- Model registry → Model providers: creates providers (evidence: `src/lib/models/registry.ts`)
- Provider settings → Configuration API: configures providers
- User → Discover feed: browses articles
- Discover feed → SearxNG search: fetches content (evidence: `src/app/api/discover/route.ts`)
- User → Image and video search: searches media
- User → Query suggestions: gets suggestions
- User → File processing: uploads files
