How itzcrazykns/perplexica works
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.