Skip to main content
Perplexica is a Next.js application that combines an AI chat experience with intelligent search. This page covers the key components and how they work together. For a high-level flow of how questions are answered, see How it works.

​
Key components

Perplexica’s architecture is organized into several key layers:

​
User interface

A web-based UI that lets users chat, search, and view citations. Built with Next.js app router.
  • Components (src/components): Reusable UI components
  • Pages and routes (src/app): Next.js app directory structure
    • Home (/)
    • Chat (/c)
    • Discover (/discover)
    • Library (/library)

​
API routes

Server endpoints implemented with Next.js route handlers in src/app/api:

Chat API

POST /api/chat - Powers the interactive chat UI with streaming responses

Search API

POST /api/search - Provides a programmatic search endpoint for integrations

Providers API

GET /api/providers - Lists available AI providers and model configurations

Media APIs

POST /api/images and POST /api/videos - Dedicated endpoints for visual search

​
Agents and orchestration

The core search intelligence lives in src/lib/agents/search:
1

Classification

The system first classifies the question using classifier.ts:
  • Determines if research is needed
  • Decides which widgets should run
  • Rewrites the query into a standalone form
Location: src/lib/agents/search/classifier.ts:37
2

Parallel execution

Research and widgets run in parallel for optimal performance:
  • Research: Gathers information from enabled sources
  • Widgets: Provides structured data (weather, stocks, calculations)
Location: src/lib/agents/search/index.ts:61-95
3

Answer generation

The final answer is generated with citations:
  • Uses search results as context
  • Includes widget data (non-citable)
  • Streams the response to the user
Location: src/lib/agents/search/index.ts:122-166

​
Research system

The researcher (src/lib/agents/search/researcher/) gathers information using multiple tools:
Research tools are located in src/lib/agents/search/researcher/actions/:
  • Web search (webSearch.ts): General web results via SearXNG
  • Academic search (academicSearch.ts): Scholarly papers and research
  • Social search (socialSearch.ts): Discussion forums and social platforms
  • Upload search (uploadsSearch.ts): Semantic search over user-uploaded files
  • URL scraping (scrapeURL.ts): Direct content extraction from specific URLs
Tools are registered in src/lib/agents/search/researcher/actions/index.ts.

​
Widgets

Widgets provide structured, real-time data and run in parallel with research:
  • Weather widget (src/lib/agents/search/widgets/weatherWidget.ts): Current conditions and forecasts
  • Stock widget (src/lib/agents/search/widgets/stockWidget.ts): Market data and prices
  • Calculation widget (src/lib/agents/search/widgets/calculationWidget.ts): Mathematical expressions
Widget execution is coordinated by src/lib/agents/search/widgets/executor.ts.
Widget results are displayed in the UI but are not cited as sources. They provide helpful context that the model can reference when generating answers.

​
Search backend

A meta-search backend fetches relevant web results when research is enabled:
  • SearXNG integration (src/lib/searxng.ts): Privacy-focused meta-search
  • Requires JSON format enabled
  • Wolfram Alpha engine should be enabled for calculations

​
LLMs (Large language models)

Used throughout the system for:
  • Classification: Analyzing queries and planning responses
  • Answer generation: Writing coherent, cited responses
  • Query rewriting: Creating standalone search queries
Provider system:
  • Providers are defined in src/lib/models/providers/
  • Model registry: src/lib/models/registry.ts
  • Supports local (Ollama) and cloud providers (OpenAI, Anthropic, Groq, etc.)

​
Embedding models

Used for semantic search over user-uploaded files:
  • Enable searching PDFs, text files, and images by meaning
  • Integrated with the uploads search action
  • Provider-agnostic architecture

​
Storage

Chats and messages are persisted so conversations can be reloaded:
  • Database: src/lib/db/
  • Schema: src/lib/db/schema.ts
  • Migrations run automatically on startup
  • Stores chat history, messages, and response blocks

​
Data flow

Here’s how data flows through the system when you ask a question:
  1. User sends message → POST /api/chat
  2. Classification → Determines research needs and widget relevance
  3. Parallel execution:
    • Researcher gathers information from enabled sources
    • Widgets fetch structured data
  4. Context assembly → Search results and widget data combined
  5. Answer generation → LLM streams response with citations
  6. Storage → Message and response saved to database
For detailed workflow and step-by-step execution, see the How it works guide.

​
Prompt templates

Prompt engineering is centralized in src/lib/prompts/:
  • Classifier prompt: Guides the classification step
  • Writer prompt: Controls answer generation and citation format
  • Research prompts: Direct tool usage during research
Prompts adapt based on:
  • Optimization mode (speed, balanced, quality)
  • System instructions (user-defined)
  • Available context (search results, widgets)

​
Configuration

Perplexica uses a flexible configuration system:
  • Setup screen: First-run configuration at http://localhost:3000
  • API keys: Provider credentials stored securely
  • Model selection: Choose models per provider
  • Search backend: SearXNG URL configuration
  • Sources: Enable/disable research sources

​
Next steps

How it works

Understand the high-level flow of answering questions

Contributing

Learn how to contribute to Perplexica’s codebase

Build docs developers (and LLMs) love

Get started for freeTalk to us