# haddadrm/perplexica architecture

> Architecture diagram of the GitHub repository haddadrm/perplexica, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haddadrm/perplexica
- Repository: https://github.com/haddadrm/perplexica

## Overview

##### Project Type and Purpose
- Perplexica is an open-source, full-stack AI-powered search engine inspired by Perplexity AI. It integrates various AI/LLM providers and leverages components like SearxNG for metasearch functionality. The purpose is to perform web searches, refine results using advanced algorithms (e.g., similarity searching and embeddings), and provide rich answers through multiple “focus modes” (academic, Reddit, YouTube, etc.).
- The README outlines two primary modes (Copilot and Normal) as well as features for image, video search, and an API endpoint to integrate within other applications.

##### File Structure Analysis and Architectural Hints
- Top-level directories:
- The “src” directory contains the server’s TypeScript source code with separate subdirectories for application logic (app.ts), chains (agents for handling search queries for images, video, suggestions, etc.), database functionality (“db”), library utilities, routes, websockets (indicating real-time communications), and utility functions.
- The “ui” directory comprises the frontend application built with React/Next.js (note files like page.tsx, layout.tsx) along with supporting configuration (Tailwind, ESLint, and Prettier).
- The presence of Docker-related files (docker-compose.yaml, multiple Dockerfiles, and docs on configuration) indicates containerization for deployment.
- There are provider files (inside src/lib/providers) that integrate with external AI/LLM services (OpenAI, Anthropic, Ollama, etc.), suggesting the backend delegates processing tasks to these providers.
- Architectural patterns:
- The design separates the backend (API routes, websockets for real-time processing, chain agents for search enhancement) from the frontend UI.
- There is a modular structure (e.g., chains, providers) that hints at a plug-and-play design for integrating multiple AI models and search capabilities.
- Interaction with SearxNG (an external metasearch engine, referenced as “searxng” directory and configuration files) underscores that the system’s search functionality is built around both internal processing and external data sources.

##### Main Components
a. Frontend/UI:
- “ui” directory’s Next.js application.
- Components (pages, layout, and various UI elements for chat, search results, and configuration settings).
- State management and client-side interaction along with API calls.
b. Backend/API Server:
- Core service running from the “src” directory.
- Modules such as:
- App.ts for entry point.
- Routes for handling REST API requests (chats, search, uploads, etc.).
- Chain agents under “src/chains” that process search queries (imageSearchAgent, videoSearchAgent, suggestionGeneratorAgent, etc.).
- Database components (“src/db”), including schema and index files.
- Utility modules for logging, message validation, and data processing.
- Websocket server components for real-time communication (connectionManager, messageHandler).
c. External Services & Providers:
d. Data and Configuration:
- The “data” directory (if it holds assets, logs, or indexes).
- Configuration files (sample.config.toml, drizzle.config.ts) that manage environmental variables and settings.
e. Containerization & Deployment:
- Containers orchestrated via docker-compose (show a container for the backend, one for the frontend, and other auxiliary containers if applicable).
- Components for Docker (app.dockerfile, backend.dockerfile) to indicate environment isolation.

##### Relationships and Interactions
- From the Frontend (UI) to the Backend API for search queries and chat requests.
- From the API to SearxNG for metasearch responses.
- From the API to LLM providers/chain agents (showing dependency towards various AI services for processing).
- Websocket connections between the UI and backend for real-time communications.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Distinguish between frontend and backend clearly.
- Modularization: Represent chain agents, providers, and routes as independent modules that work together.
- Scalability: Indicate how Docker containers are used for deployment—this helps in scaling parts of the system individually.
- Extensibility: Highlight integration points with additional search modes and LLM providers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/User
    User["User"]:::client

    %% Frontend (Next.js UI)
    subgraph "Frontend (Next.js UI)"
        Pages["Pages (ui/app)"]:::frontend
        Components["UI Components (ui/components)"]:::frontend
        FrontendUtils["Frontend Utils (ui/lib)"]:::frontend
    end

    %% Backend API
    subgraph "Backend API"
        APIServer["API Server (src/app.ts)"]:::backend
        Routes["Routes (src/routes)"]:::backend
        ChainAgents["Chain Agents (src/chains)"]:::backend
        Database["Database (src/db)"]:::backend
        WebSocket["WebSocket Server (src/websocket)"]:::backend
        Providers["Providers (src/lib/providers)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        SearxNG["SearxNG Metasearch (searxng)"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        DataDir["Data Assets (data)"]:::infra
        ConfigFiles["Configuration Files (sample.config.toml, drizzle.config.ts)"]:::infra
        DockerCompose["Docker Compose (docker-compose.yaml)"]:::infra
        DockerApp["Dockerfile: App (app.dockerfile)"]:::infra
        DockerBackend["Dockerfile: Backend (backend.dockerfile)"]:::infra
    end

    %% Relationships and Data Flow
    User -->|"HTTPReqs"| Pages
    Pages -->|"API_Call"| APIServer
    Pages -->|"WebSocket"| WebSocket
    APIServer -->|"REST"| Routes
    APIServer -->|"ProcessQuery"| ChainAgents
    ChainAgents -->|"LLM_Calls"| Providers
    APIServer -->|"DB_Ops"| Database
    APIServer -->|"SearchQuery"| SearxNG
    ConfigFiles ---|"Feeds"| APIServer
    ConfigFiles ---|"Feeds"| Pages
    DockerCompose ---|"Orchestrates"| APIServer
    DockerCompose ---|"Orchestrates"| Pages
    DockerApp ---|"Builds"| APIServer
    DockerBackend ---|"Builds"| APIServer

    %% Click Events for Frontend/UI
    click Pages "https://github.com/haddadrm/perplexica/tree/master/ui/app"
    click Components "https://github.com/haddadrm/perplexica/tree/master/ui/components"
    click FrontendUtils "https://github.com/haddadrm/perplexica/tree/master/ui/lib"

    %% Click Events for Backend/API Server
    click APIServer "https://github.com/haddadrm/perplexica/blob/master/src/app.ts"
    click Routes "https://github.com/haddadrm/perplexica/tree/master/src/routes"
    click ChainAgents "https://github.com/haddadrm/perplexica/tree/master/src/chains"
    click Database "https://github.com/haddadrm/perplexica/tree/master/src/db"
    click WebSocket "https://github.com/haddadrm/perplexica/tree/master/src/websocket"
    click Providers "https://github.com/haddadrm/perplexica/tree/master/src/lib/providers"

    %% Click Event for External Metasearch Engine
    click SearxNG "https://github.com/haddadrm/perplexica/tree/master/searxng"

    %% Click Events for Infrastructure & Deployment
    click DataDir "https://github.com/haddadrm/perplexica/tree/master/data"
    click ConfigFiles "https://github.com/haddadrm/perplexica/blob/master/sample.config.toml"
    click DockerCompose "https://github.com/haddadrm/perplexica/blob/master/docker-compose.yaml"
    click DockerApp "https://github.com/haddadrm/perplexica/blob/master/app.dockerfile"
    click DockerBackend "https://github.com/haddadrm/perplexica/blob/master/backend.dockerfile"

    %% Class Definitions for Colors and Style
    classDef frontend fill:#ccf,stroke:#333,stroke-width:2px;
    classDef backend fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fcc,stroke:#333,stroke-width:2px;
    classDef infra fill:#eee,stroke:#333,stroke-width:2px;
    classDef client fill:#ffc,stroke:#333,stroke-width:2px;
```
