Skip to main content
Thanks for your interest in contributing to Perplexica! Your help makes this project better. This guide explains how to contribute effectively and where to make changes.

​
Getting started

Perplexica is a modern AI chat application with advanced search capabilities. Before contributing, familiarize yourself with:

​
Project structure

Perplexica’s codebase is organized into clear, logical sections:

​
Frontend (UI)

  • 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 (src/app/api): Server endpoints using Next.js route handlers

​
Backend (Core logic)

Located in src/lib/, this contains all backend functionality:
  • Search system (src/lib/agents/search): Core chat and search pipeline
  • Database (src/lib/db): Database functionality and schema
  • Models (src/lib/models):
    • Providers in src/lib/models/providers
    • Registry in src/lib/models/registry.ts
  • Prompts (src/lib/prompts): Prompt templates
  • SearXNG (src/lib/searxng.ts): Search backend integration
  • Uploads (src/lib/uploads): File upload and semantic search

​
Search pipeline

The search system is split into four key phases:
1

Classification

src/lib/agents/search/classifier.ts - Decides whether research is needed and what should run
2

Research

src/lib/agents/search/researcher/ - Gathers information in the background
3

Widgets

src/lib/agents/search/widgets/ - Runs parallel structured data helpers
4

Writing

Uses prompts from src/lib/prompts/search/writer.ts to generate cited answers

​
Where to make changes

Use this section as a map for common contribution types:

​
Search behavior and reasoning

Core search pipeline

Location: src/lib/agents/search
  • Classifier (classifier.ts): Modify how questions are analyzed
  • Researcher (researcher/): Change how information is gathered
  • Main flow (index.ts): Adjust overall orchestration
Example: Change when research is triggered or how results are ranked

​
Add or change search capabilities

Research tools

Location: src/lib/agents/search/researcher/actionsAvailable tools:
  • webSearch.ts - General web results
  • academicSearch.ts - Scholarly papers
  • socialSearch.ts - Discussion forums
  • uploadsSearch.ts - User file search
  • scrapeURL.ts - Direct URL scraping
To add a new tool:
  1. Create a new file in actions/ (e.g., newsSearch.ts)
  2. Implement the tool interface
  3. Register it in actions/index.ts
Example: Add a news-specific search tool or integrate a new search API

​
Add or change widgets

Widget system

Location: src/lib/agents/search/widgetsExisting widgets:
  • weatherWidget.ts - Weather forecasts
  • stockWidget.ts - Stock prices
  • calculationWidget.ts - Math expressions
Widgets run in parallel with research and show structured results in the UI.To add a new widget:
  1. Create a file (e.g., newsWidget.ts)
  2. Implement the widget interface
  3. Add classification logic in classifier.ts
  4. Register in widgets/index.ts
Example: Add a timezone converter or currency exchange widget

​
Model integrations

AI providers

Location: src/lib/models/providersAdd new AI providers:
  1. Create a provider file (e.g., groq.ts)
  2. Implement the provider interface
  3. Wire into src/lib/models/registry.ts
  4. Provider will appear in the setup UI
Example: Add support for a new LLM API like Cohere or Together AI

​
UI components

Interface changes

Location: src/componentsModify or add UI components:
  • Chat interface
  • Widget displays
  • Settings panels
  • Citation rendering
Example: Improve the citation display or add dark mode support

​
API endpoints

API routes

Location: src/app/apiKey endpoints:
  • chat/route.ts - Main chat API
  • search/route.ts - Programmatic search
  • images/route.ts - Image search
  • videos/route.ts - Video search
  • providers/route.ts - Provider management
Example: Add rate limiting or new query parameters

​
Setting up your environment

Before diving into coding, set up your local development environment:
1

Install dependencies

npm install
2

Start development server

npm run dev
The app will be available at http://localhost:3000
3

Complete setup

Open http://localhost:3000 and complete the setup in the UI:
  • Add API keys for your chosen providers
  • Select models
  • Configure search backend URL (SearXNG)
  • Enable desired sources
4

Verify database

Database migrations are applied automatically on startup. No manual migration needed.
For Docker-based development, see the installation guide in the repository README. Docker is recommended for production, while npm run dev is used for development.

​
Coding practices

Follow these guidelines to maintain code quality and consistency:

​
Before committing

1

Test your changes

Ensure your code functions correctly through thorough testing:
  • Test in the UI
  • Test API endpoints
  • Verify database changes
2

Format your code

Always run the formatter before committing:
npm run format:write
This maintains consistency and code quality across the project.
3

Review your changes

Double-check:
  • No debug code left behind
  • Comments explain complex logic
  • New files are in the right location

​
Code style

  • TypeScript: Use strict typing, avoid any
  • Naming: Use descriptive variable and function names
  • Comments: Explain the “why”, not the “what”
  • Error handling: Always handle errors gracefully
  • Async/await: Prefer over .then() chains

​
Testing

While Perplexica doesn’t currently have automated tests:
  • Manually test your changes thoroughly
  • Test different AI providers
  • Test with and without search enabled
  • Check edge cases (empty queries, long responses, etc.)

​
Contribution workflow

1

Fork and clone

  1. Fork the repository on GitHub
  2. Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/Perplexica.git
cd Perplexica
2

Create a branch

Create a feature branch for your changes:
git checkout -b feature/my-new-feature
Use descriptive branch names like:
  • feature/add-news-search
  • fix/citation-rendering
  • docs/update-api-guide
3

Make your changes

Implement your feature or fix following the coding practices above.
4

Commit

Write clear, descriptive commit messages:
git add .
git commit -m "Add news search tool to researcher actions"
5

Push and PR

Push to your fork and create a pull request:
git push origin feature/my-new-feature
Then open a PR on GitHub with:
  • Clear description of changes
  • Why the change is needed
  • How to test it

​
API documentation

If you’re modifying APIs, update the API documentation:
  • Search API: See docs/API/SEARCH.md in the source repository
  • Document new endpoints or parameters
  • Include request/response examples

​
Architecture documentation

If you’re making significant architectural changes:
  • Update docs/architecture/README.md for component changes
  • Update docs/architecture/WORKING.md for workflow changes
  • Keep documentation in sync with code

​
Community guidelines

While Perplexica doesn’t yet have a formal code of conduct:
  • Be respectful and professional
  • Provide constructive feedback
  • Help other contributors
  • Report bugs clearly with reproduction steps
  • Discuss significant changes before implementing

​
Getting help

Discord Community

Join the Discord server for real-time help and discussions

GitHub Issues

Report bugs or request features on GitHub

​
Recognition

Contributors are recognized in:
  • GitHub contributors page
  • Project README
  • Release notes for significant contributions
Thank you for helping make Perplexica better! Every contribution, no matter how small, is valuable and appreciated.

​
Next steps

Architecture

Understand the component-level architecture

How it works

Learn the high-level flow of answering questions

Build docs developers (and LLMs) love

Get started for freeTalk to us