Perplexica - Moses Yebei

The Problem

Users who need on‑premise, citation‑backed answers must stitch together a web server, LLM providers, a search backend and a UI. Doing this manually requires wiring many moving parts, handling secret keys, and keeping the data flow private.

What This Does

Perplexica delivers a self‑hosted Next.js application that exposes a REST‑style API (src/app/api/**) and a React front‑end. The search flow lives in src/lib/agents/search/, with provider adapters in src/lib/models/providers/ (e.g., OpenAI, Anthropic, Ollama). Configuration and persistence are handled by src/lib/config/ and src/lib/db/.

Key files:

src/app/api/search/route.ts – HTTP handler that starts a search (start).
src/lib/agents/search/index.ts – searchAsync orchestrates the researcher.
src/lib/models/providers/anthropic/index.ts – loads chat and embedding models (loadChatModel, loadEmbeddingModel).
src/lib/hooks/useChat.tsx – central hook that maintains chat state and talks to the model.

The UI components (src/components/**) render messages, settings and widgets (weather, stock, calculation) that are injected by the search agents.

How It Is Wired

Execution begins when Next.js routes a POST to /api/search. The handler in src/app/api/search/route.ts (function start at line 119) validates the request and calls src/lib/agents/search/index.ts → searchAsync.

searchAsync (line 13) creates a Researcher (src/lib/agents/search/researcher/index.ts) and invokes its research method. research (line 10) runs a registry of actions (src/lib/agents/search/researcher/actions/registry.ts) that eventually call search (in src/lib/agents/search/researcher/actions/webSearch.ts etc.).

search updates the chat block via src/lib/hooks/useChat.tsx → updateBlock, then calls the selected provider. For cloud models the path is:

searchAsync → research → streamText → this.openAIClient.chat.completions.create

For local Ollama models the call chain is:

searchAsync → research → streamText → src/lib/models/providers/ollama/ollamaLLM.ts → generateText

All database writes funnel through src/lib/db/index.ts (e.g., persisting chat history). File uploads are managed by src/lib/uploads/manager.ts and stored via src/lib/uploads/store.ts.

The most‑used internal symbols are useChat (called from 13 places) and saveConfig (8 callers). src/lib/agents/search/types.ts is a hub module with 17 inbound imports; changes there have a wide blast radius.

Circular imports involve 11 modules, notably src/lib/models/types.ts, src/components/ChatWindow.tsx, and src/lib/types.ts. These cycles increase build‑time fragility and make refactoring risky.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Perplexica
cd Perplexica

# Install dependencies (Yarn is the declared manager)
yarn install

# Run locally with Next.js
yarn dev   # starts the dev server on http://localhost:3000

# Or spin up the Docker composition (Dockerfile and docker‑compose.yaml are present)
docker compose up --build

Configuration files are expected under src/lib/config/ (e.g., clientRegistry.ts, serverRegistry.ts). The repository does not contain a sample .env – you must supply API keys for any external LLM provider (OpenAI, Anthropic, etc.) and the SearxNG endpoint as described in the docs (docs/API/SEARCH.md).

The API is reachable at POST /api/search with a JSON body matching SearchRequestBody (defined in src/lib/types.ts). The UI is served from the same Next.js process.

Real‑World Use

A corporate knowledge‑base portal could embed Perplexica as a micro‑service. An internal tool sends a user query to /api/search; the service fetches web results via SearxNG, runs them through a locally hosted Ollama LLM, and returns a markdown answer with citations. The front‑end component src/components/MessageRenderer/CodeBlock renders any code snippets, while src/components/Widgets/Weather.tsx displays weather widgets when relevant.

Code Health & Issues

HIGH – Pin third‑party GitHub Actions to commit SHAs (.github/workflows/docker-build.yaml).
HIGH – No test suite; 160 source files lack any test files.
MEDIUM – GitHub token permissions are not declared (docker-build.yaml).
MEDIUM – Dependabot/Renovate not configured (package.json present, no bot).
MEDIUM – Docker base image not pinned by digest (Dockerfile).
MEDIUM – No dependency‑vulnerability scan in CI.
MEDIUM – Large binary (.assets/demo.gif, 31 MB) should be moved to LFS or external storage.
LOW – CI jobs lack timeout-minutes (docker-build.yaml).

Additional static findings: 11 import cycles, deep nesting in several UI components, a 712‑line useChat.tsx hook, duplicated route logic across API files, and an empty catch block in src/app/api/search/route.ts.

The Bottom Line

Perplexica provides a functional, privacy‑first AI answering stack with a clear separation between search, LLM providers and UI. It runs out‑of‑the‑box via Docker or Yarn, but the codebase suffers from missing tests, import cycles and several maintainability hotspots. It is suitable for teams that need a self‑hosted answer engine and are prepared to invest in refactoring and test coverage.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

234 files

TypeScript97
TSX60
Markdown9
JSON8
YAML3
SQL3

ReactNext.jsTailwindDockerTransformers

Module dependencies

The 10 most depended-upon modules of 160, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_lib_agents_search_types["types"] n1_src_lib_models_types["types"] n2_rc_lib_models_base_embedding["embedding"] n3_src_lib_models_base_llm["llm"] n4_src_lib_models_base_provider["provider"] n5_src_components_ChatWindow["ChatWindow"] n6_s_providers_openai_openaiLLM["openaiLLM"] n7_src_lib_types["types"] n8_iders_openai_openaiEmbedding["openaiEmbedding"] n9_nents_Settings_SettingsField["SettingsField"] n0_src_lib_agents_search_types --> n3_src_lib_models_base_llm n3_src_lib_models_base_llm --> n1_src_lib_models_types n4_src_lib_models_base_provider --> n1_src_lib_models_types n4_src_lib_models_base_provider --> n3_src_lib_models_base_llm n4_src_lib_models_base_provider --> n2_rc_lib_models_base_embedding n8_iders_openai_openaiEmbedding --> n2_rc_lib_models_base_embedding n6_s_providers_openai_openaiLLM --> n3_src_lib_models_base_llm n6_s_providers_openai_openaiLLM --> n1_src_lib_models_types n1_src_lib_models_types --> n7_src_lib_types n7_src_lib_types --> n1_src_lib_models_types classDef cyc stroke:#ef4444,stroke-width:2px; class n1_src_lib_models_types,n5_src_components_ChatWindow,n7_src_lib_types cyc;

Dependencies

24 of 56 declared dependencies are a major version behind. Resolved 56 of 56 against the registry.

Package	Declared	Latest	Behind
`react-text-to-speech`	^0.14.5	5.1.10	5 major
`better-sqlite3`	^11.9.1	13.0.3	2 major
`markdown-to-jsx`	^7.7.2	9.10.2	2 major
`officeparser`	^5.2.2	7.6.2	2 major
`@types/better-sqlite3`	^7.6.12	9.6.0	2 major
`@types/node`	^24.8.1	26.2.0	2 major
`eslint`	^8	10.8.1	2 major
`eslint-config-next`	14.1.4	16.3.1	2 major

Findings

MediumNo test files detected - untested code paths repository-wide

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

docker/setup-buildx-action@v2, docker/login-action@v2

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a test suite; this repository has nonehigh160 occurrences

160 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/docker-build.yaml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:24.5.0-slim, node:24.5.0-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium

.assets/demo.gif

1 blobs over 5MB: demo.gif 31.2MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set timeout-minutes on the workflow jobslow

.github/workflows/docker-build.yaml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.