> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ItzCrazyKns/Perplexica/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> Component-level architecture overview of Perplexica's search and AI system
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](/advanced/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`:
`POST /api/chat` - Powers the interactive chat UI with streaming responses
`POST /api/search` - Provides a programmatic search endpoint for integrations
`GET /api/providers` - Lists available AI providers and model configurations
`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`:
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`
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`
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](/advanced/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](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
Understand the high-level flow of answering questions
Learn how to contribute to Perplexica's codebase