# itzcrazykns/perplexica architecture

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

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

## Overview

##### Project type and purpose
- Perplexica is a full-stack AI-powered search engine built with Next.js (React/TypeScript) for the frontend and Node.js/TypeScript serverless API routes for the backend.
- It integrates with SearxNG (an open-source meta-search engine), various LLM providers (OpenAI, Ollama, Anthropic, Groq, etc.), and a SQL database managed via Drizzle ORM.

##### File structure
- Top-level orchestration:
- docker-compose.yaml, app.dockerfile, entrypoint.sh – define containers (Next.js app, SearxNG service, database).
- sample.config.toml → config.toml – runtime settings for API keys and endpoints.
- Frontend:
- src/app – Next.js App Router (server/edge components, global layout, pages under /api).
- src/components – reusable UI components (ChatWindow, MessageInput, Widgets).
- public, .assets – static assets and screenshots.
- Backend:
- src/app/api – Next.js API route handlers (chat, search, config, uploads, weather, etc.).
- src/lib – core logic (“chains” folder for orchestrating LLM chains, “providers” for external LLMs, “search” for meta-search; “db” using Drizzle).
- drizzle.config.ts + drizzle/ folder – database migration files and schema snapshots.
- Configuration & tooling:
- next.config.mjs, tsconfig.json, tailwind.config.ts, ESLint/Prettier configs.
- .github/workflows/docker-build.yaml for CI/CD.

##### README for insights
- Describes two main modes (Normal vs. Copilot) and six Focus Modes.
- Mentions API endpoints (see docs/API), settings page, history saving, discover.
- Deployment targets: Docker Compose, one-click cloud deployments.

1. Client (Browser/Mobile) – React UI (Next.js pages & components)
2. Next.js Serverless Backend – API Route Layer (src/app/api)
3. Business Logic Layer – Chains & Agents (src/lib/chains, src/lib/search)
4. Provider Interfaces – LLM Providers (src/lib/providers)
5. Meta-Search Engine – SearxNG Service (container, settings in searxng/ )
6. Database – SQL managed via Drizzle ORM (drizzle.config.ts, drizzle/)
7. File Store – uploads directory (for user uploads)
8. External Internet – Web & Media Sources (for scraping, citations)
9. DevOps/Infrastructure – Docker Compose, CI/CD workflow.

- Client → API Routes: HTTP requests (search, chat, config, uploads)
- API Routes → Chains Layer: hand off query/context to chain orchestrator
- Chains → Provider Interfaces: call LLM endpoints (OpenAI, Ollama, etc.)
- Chains → SearxNG: HTTP request for search results (JSON)
- Chains → External Internet: follow-up HTTP crawls (Copilot Mode)
- API Routes → Database: read/write chat/history/config via Drizzle ORM
- API Routes → File Store: handle file uploads/downloads
- Backend → Client: send aggregated responses (messages, citations, images)

c. Architectural patterns & design principles:
- “Layered” architecture: UI → API → Business Logic → Persistence/External Services.
- Modular design: separate “chains”, “providers”, “db”, “utils” in src/lib.
- Serverless style APIs embedded within Next.js.
- Infrastructure as code: Docker Compose for local dev and deployments.

d. Key technologies/frameworks:
- Frontend: Next.js (React 18), Tailwind CSS, TypeScript.
- Backend: Next.js API Routes, Drizzle ORM (TypeScript migrations), Node.js.
- Search: SearxNG (uwsgi container, settings.yml).
- LLM Providers: OpenAI, Ollama, Anthropic, Groq, Deepseek, AIMLAPI.
- Deployment: Docker, docker-compose, CI/CD via GitHub Actions.

##### Essential details to capture
- All Next.js API routes (group under “API Routes” node).
- The Drizzle migration flow (config → migrations → schema).
- The Docker Compose network linking Next.js, SearxNG, and the database.
- The “Chain” logic layer calling both SearxNG and LLM providers.
- The Client’s focus modes and how they translate into different chain configurations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier"
        ClientUI["Client (React UI)"]:::ui
    end

    %% API Tier
    subgraph "API Tier"
        API["API Routes<br/>(src/app/api)"]:::api
    end

    %% Business Logic Tier
    subgraph "Business Logic Tier"
        Chains["Chains & Search<br/>(src/lib/chains, src/lib/search)"]:::logic
        Providers["LLM Providers<br/>(src/lib/providers)"]:::external
    end

    %% Persistence Tier
    subgraph "Persistence Tier"
        DB["Drizzle SQL Database"]:::persist
        FileStore["File Store (uploads)"]:::persist
    end

    %% External Services Tier
    subgraph "External Services"
        SearxNG["SearxNG Service"]:::external
        Internet["External Internet"]:::external
    end

    %% Connections
    ClientUI -->|"HTTP Requests"| API
    API -->|"invoke Chains"| Chains
    Chains -->|"call Providers"| Providers
    Chains -->|"search requests"| SearxNG
    Chains -->|"crawl follow-ups"| Internet
    API -->|"DB.read/write"| DB
    API -->|"File uploads/downloads"| FileStore
    API -->|"HTTP Responses"| ClientUI

    %% Click Events
    click ClientUI "https://github.com/itzcrazykns/perplexica/blob/master/src/app/layout.tsx"
    click ClientUI "https://github.com/itzcrazykns/perplexica/blob/master/src/app/page.tsx"
    click ClientUI "https://github.com/itzcrazykns/perplexica/blob/master/src/app/globals.css"
    click ClientUI "https://github.com/itzcrazykns/perplexica/tree/master/src/components"
    click API "https://github.com/itzcrazykns/perplexica/tree/master/src/app/api"
    click Chains "https://github.com/itzcrazykns/perplexica/tree/master/src/lib/chains"
    click Chains "https://github.com/itzcrazykns/perplexica/tree/master/src/lib/search"
    click Providers "https://github.com/itzcrazykns/perplexica/tree/master/src/lib/providers"
    click SearxNG "https://github.com/itzcrazykns/perplexica/tree/master/searxng"
    click DB "https://github.com/itzcrazykns/perplexica/blob/master/drizzle.config.ts"
    click DB "https://github.com/itzcrazykns/perplexica/tree/master/drizzle/"
    click FileStore "https://github.com/itzcrazykns/perplexica/tree/master/uploads"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#000,stroke-width:1px;
    classDef api fill:#DFFFD0,stroke:#000,stroke-width:1px;
    classDef logic fill:#F0F8FF,stroke:#000,stroke-width:1px;
    classDef persist fill:#FFE5B4,stroke:#000,stroke-width:1px;
    classDef external fill:#E8D0FF,stroke:#000,stroke-width:1px;
```
