> ## 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.

# Contributing

> How to contribute to the Perplexica project and improve the codebase

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:

* [Architecture](/advanced/architecture): Component-level overview
* [How it works](/advanced/how-it-works): High-level flow
* The codebase structure (explained below)

## Project structure

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

### Frontend (UI)

<Accordion title="Components and pages">
  * **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
</Accordion>

### Backend (Core logic)

<Accordion title="Backend functionality">
  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
</Accordion>

### Search pipeline

The search system is split into four key phases:

<Steps>
  <Step title="Classification">
    `src/lib/agents/search/classifier.ts` - Decides whether research is needed and what should run
  </Step>

  <Step title="Research">
    `src/lib/agents/search/researcher/` - Gathers information in the background
  </Step>

  <Step title="Widgets">
    `src/lib/agents/search/widgets/` - Runs parallel structured data helpers
  </Step>

  <Step title="Writing">
    Uses prompts from `src/lib/prompts/search/writer.ts` to generate cited answers
  </Step>
</Steps>

## Where to make changes

Use this section as a map for common contribution types:

### Search behavior and reasoning

<Card title="Core search pipeline" icon="magnifying-glass">
  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
</Card>

### Add or change search capabilities

<Card title="Research tools" icon="wrench">
  Location: `src/lib/agents/search/researcher/actions`

  Available 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
</Card>

### Add or change widgets

<Card title="Widget system" icon="puzzle-piece">
  Location: `src/lib/agents/search/widgets`

  Existing 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
</Card>

### Model integrations

<Card title="AI providers" icon="brain">
  Location: `src/lib/models/providers`

  Add 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
</Card>

### UI components

<Card title="Interface changes" icon="window">
  Location: `src/components`

  Modify or add UI components:

  * Chat interface
  * Widget displays
  * Settings panels
  * Citation rendering

  Example: Improve the citation display or add dark mode support
</Card>

### API endpoints

<Card title="API routes" icon="code">
  Location: `src/app/api`

  Key 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
</Card>

## Setting up your environment

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

<Steps>
  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Start development server">
    ```bash theme={null}
    npm run dev
    ```

    The app will be available at [http://localhost:3000](http://localhost:3000)
  </Step>

  <Step title="Complete setup">
    Open [http://localhost:3000](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
  </Step>

  <Step title="Verify database">
    Database migrations are applied automatically on startup. No manual migration needed.
  </Step>
</Steps>

<Note>
  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.
</Note>

## Coding practices

Follow these guidelines to maintain code quality and consistency:

### Before committing

<Steps>
  <Step title="Test your changes">
    Ensure your code functions correctly through thorough testing:

    * Test in the UI
    * Test API endpoints
    * Verify database changes
  </Step>

  <Step title="Format your code">
    Always run the formatter before committing:

    ```bash theme={null}
    npm run format:write
    ```

    This maintains consistency and code quality across the project.
  </Step>

  <Step title="Review your changes">
    Double-check:

    * No debug code left behind
    * Comments explain complex logic
    * New files are in the right location
  </Step>
</Steps>

### 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

<Steps>
  <Step title="Fork and clone">
    1. Fork the repository on GitHub
    2. Clone your fork locally:

    ```bash theme={null}
    git clone https://github.com/YOUR_USERNAME/Perplexica.git
    cd Perplexica
    ```
  </Step>

  <Step title="Create a branch">
    Create a feature branch for your changes:

    ```bash theme={null}
    git checkout -b feature/my-new-feature
    ```

    Use descriptive branch names like:

    * `feature/add-news-search`
    * `fix/citation-rendering`
    * `docs/update-api-guide`
  </Step>

  <Step title="Make your changes">
    Implement your feature or fix following the coding practices above.
  </Step>

  <Step title="Commit">
    Write clear, descriptive commit messages:

    ```bash theme={null}
    git add .
    git commit -m "Add news search tool to researcher actions"
    ```
  </Step>

  <Step title="Push and PR">
    Push to your fork and create a pull request:

    ```bash theme={null}
    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
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/26aArMy8tT">
    Join the Discord server for real-time help and discussions
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/ItzCrazyKns/Perplexica/issues">
    Report bugs or request features on GitHub
  </Card>
</CardGroup>

## 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

<CardGroup cols={2}>
  <Card title="Architecture" icon="building" href="/advanced/architecture">
    Understand the component-level architecture
  </Card>

  <Card title="How it works" icon="gears" href="/advanced/how-it-works">
    Learn the high-level flow of answering questions
  </Card>
</CardGroup>