How ramstorageai/perplexica works
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: route.ts Chat endpoint · search/index.ts Search agent · api.ts API search agent · researcher/index.ts Research agent
Components 22
User experience
- Chat interface
src/components/ChatWindow.tsx - Chat state
src/lib/hooks/useChat.tsx - Provider settings
src/components/Settings/Sections/Models/ModelProvider.tsx
Answer orchestration
- Chat endpoint
src/app/api/chat/route.ts - Search endpoint
src/app/api/search/route.ts - Search agent
src/lib/agents/search/index.ts - API search agent
src/lib/agents/search/api.ts - Stream session
src/lib/session.ts
Search capabilities
- Query classifier
src/lib/agents/search/classifier.ts - Research agent
src/lib/agents/search/researcher/index.ts - Research actions
src/lib/agents/search/researcher/actions - Answer widgets
src/lib/agents/search/widgets/index.ts - SearxNG search
src/lib/searxng.ts - File processing
src/lib/uploads/manager.ts - Image and video search
src/lib/agents/media - Query suggestions
src/lib/agents/suggestions/index.ts - Discover feed
src/app/api/discover/route.ts
Configuration and persistence
- Model registry
src/lib/models/registry.ts - Model providers
src/lib/models/providers/index.ts - Configuration API
src/lib/config/index.ts - Chat database
src/lib/db/schema.ts
Other components
- User
Connections 25
- User → Chat interface: asks questions
- Chat interface → Chat state: renders state
src/components/ChatWindow.tsx - Chat state → Chat endpoint: submits chat
- Chat endpoint → Model registry: loads models
src/app/api/chat/route.ts - Chat endpoint → Search agent: starts research
src/app/api/chat/route.ts - Chat endpoint → Stream session: streams events
src/app/api/chat/route.ts - Chat endpoint → Chat database: persists chat
src/app/api/chat/route.ts - Search endpoint → Model registry: loads models
src/app/api/search/route.ts - Search endpoint → API search agent: starts search
src/app/api/search/route.ts - API search agent → Query classifier: classifies query
src/lib/agents/search/api.ts - API search agent → Research agent: runs research
src/lib/agents/search/api.ts - API search agent → Answer widgets: executes widgets
src/lib/agents/search/api.ts - Research agent → Research actions: dispatches actions
- Research actions → SearxNG search: searches web
- Search agent → Query classifier: classifies query
src/lib/agents/search/index.ts - Search agent → Research agent: runs research
src/lib/agents/search/index.ts - Search agent → Answer widgets: executes widgets
src/lib/agents/search/index.ts - Chat endpoint → File processing: processes files
src/app/api/chat/route.ts - Model registry → Model providers: creates providers
src/lib/models/registry.ts - Provider settings → Configuration API: configures providers
- User → Discover feed: browses articles
- Discover feed → SearxNG search: fetches content
src/app/api/discover/route.ts - User → Image and video search: searches media
- User → Query suggestions: gets suggestions
- User → File processing: uploads files