From 5a44319d854847ab8795450e87a7b81291ee3984 Mon Sep 17 00:00:00 2001
From: ItzCrazyKns <95534749+ItzCrazyKns@users.noreply.github.com>
Date: Sat, 27 Dec 2025 13:09:01 +0530
Subject: [PATCH] feat(guides): update contributing guides

---
 CONTRIBUTING.md | 62 ++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 46 insertions(+), 16 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 04416e1..6b4ce5b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,33 +11,63 @@ Perplexica's codebase is organized as follows:
 - **UI Components and Pages**:
   - **Components (`src/components`)**: Reusable UI components.
   - **Pages and Routes (`src/app`)**: Next.js app directory structure with page components.
-    - Main app routes include: home (`/`), chat (`/c`), discover (`/discover`), library (`/library`), and settings (`/settings`).
-  - **API Routes (`src/app/api`)**: API endpoints implemented with Next.js API routes.
-    - `/api/chat`: Handles chat interactions.
-    - `/api/search`: Provides direct access to Perplexica's search capabilities.
-    - Other endpoints for models, files, and suggestions.
+    - Main app routes include: home (`/`), chat (`/c`), discover (`/discover`), and library (`/library`).
+  - **API Routes (`src/app/api`)**: Server endpoints implemented with Next.js route handlers.
 - **Backend Logic (`src/lib`)**: Contains all the backend functionality including search, database, and API logic.
-  - The search functionality is present inside `src/lib/search` directory.
-  - All of the focus modes are implemented using the Meta Search Agent class in `src/lib/search/metaSearchAgent.ts`.
+  - The search system lives in `src/lib/agents/search`.
+  - The search pipeline is split into classification, research, widgets, and writing.
   - Database functionality is in `src/lib/db`.
-  - Chat model and embedding model providers are managed in `src/lib/providers`.
-  - Prompt templates and LLM chain definitions are in `src/lib/prompts` and `src/lib/chains` respectively.
+  - Chat model and embedding model providers are in `src/lib/models/providers`, and models are loaded via `src/lib/models/registry.ts`.
+  - Prompt templates are in `src/lib/prompts`.
+  - SearXNG integration is in `src/lib/searxng.ts`.
+  - Upload search lives in `src/lib/uploads`.
+
+### Where to make changes
+
+If you are not sure where to start, use this section as a map.
+
+- **Search behavior and reasoning**
+
+  - `src/lib/agents/search` contains the core chat and search pipeline.
+  - `classifier.ts` decides whether research is needed and what should run.
+  - `researcher/` gathers information in the background.
+
+- **Add or change a search capability**
+
+  - Research tools (web, academic, discussions, uploads, scraping) live in `src/lib/agents/search/researcher/actions`.
+  - Tools are registered in `src/lib/agents/search/researcher/actions/index.ts`.
+
+- **Add or change widgets**
+
+  - Widgets live in `src/lib/agents/search/widgets`.
+  - Widgets run in parallel with research and show structured results in the UI.
+
+- **Model integrations**
+
+  - Providers live in `src/lib/models/providers`.
+  - Add new providers there and wire them into the model registry so they show up in the app.
+
+- **Architecture docs**
+  - High level overview: `docs/architecture/README.md`
+  - High level flow: `docs/architecture/WORKING.md`
 
 ## API Documentation
 
-Perplexica exposes several API endpoints for programmatic access, including:
+Perplexica includes API documentation for programmatic access.
 
-- **Search API**: Access Perplexica's advanced search capabilities directly via the `/api/search` endpoint. For detailed documentation, see `docs/api/search.md`.
+- **Search API**: For detailed documentation, see `docs/API/SEARCH.md`.
 
 ## Setting Up Your Environment
 
 Before diving into coding, setting up your local environment is key. Here's what you need to do:
 
-1. In the root directory, locate the `sample.config.toml` file.
-2. Rename it to `config.toml` and fill in the necessary configuration fields.
-3. Run `npm install` to install all dependencies.
-4. Run `npm run db:migrate` to set up the local sqlite database.
-5. Use `npm run dev` to start the application in development mode.
+1. Run `npm install` to install all dependencies.
+2. Use `npm run dev` to start the application in development mode.
+3. Open http://localhost:3000 and complete the setup in the UI (API keys, models, search backend URL, etc.).
+
+Database migrations are applied automatically on startup.
+
+For full installation options (Docker and non Docker), see the installation guide in the repository README.
 
 **Please note**: Docker configurations are present for setting up production environments, whereas `npm run dev` is used for development purposes.