# u14app/deep-research architecture

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

- Interactive diagram: https://gitdiagram.com/u14app/deep-research
- Repository: https://github.com/u14app/deep-research

## Overview

##### Project type and purpose
- Deep Research is a full-stack web application built with Next.js (v15) and Shadcn UI.
- It serves a React‑based frontend in the browser and a set of serverless API routes for AI model proxying and web search proxying.
- It can be deployed to Vercel, Cloudflare Pages, or run in Docker.

##### Main components
a. Client (Browser)
- Next.js App Router (src/app)
- React Components (src/components)
- State Management & Local Storage (src/store + src/utils/storage.ts)
- Editor (MilkdownEditor)
b. Next.js Server (Serverless functions)
- API Routes under src/app/api/ai/* – proxy endpoints for AI providers (OpenAI, Gemini, Anthropic, Ollama, etc.)
- API Routes under src/app/api/search/* – proxy endpoints for search engines (SearxNG, Bocha, Exa, Firecrawl, Tavily)
- Middleware (src/middleware.ts)
c. External Services
- AI Provider APIs (Google Gemini, OpenAI, Anthropic, Deepseek, OpenRouter, Ollama, etc.)
- Web Search Engine APIs (SearxNG, Bocha, Exa, Firecrawl, Tavily)
d. Deployment / Infrastructure
- Vercel Edge Functions / Cloudflare Workers (via vercel.json, wrangler.toml)
- Docker Container (Dockerfile, docker-compose.yml)
- CDN / Static File Hosting (public/, out/)

##### Relationships and data flow
1. User interacts with UI in browser → triggers React state changes or form submissions.
2. Client-side code invokes Next.js API routes (under /api) via fetch calls.
3. API route receives request → applies any middleware/auth (ACCESS_PASSWORD) → proxies request to the chosen external AI or search API (using env vars, multi-key support).
4. External service returns data → API route returns JSON to browser.
5. Browser updates state/store, renders results, and persists history to localStorage.

##### Architectural patterns and design principles
- “API Gateway” pattern: all AI/search calls go through centralized serverless endpoints.
- Separation of concerns:
- Presentation layer (components/ui + page.tsx + layout.tsx)
- Business logic/hooks (src/hooks)
- Data layer (API routes + utils + store)
- Extensibility: each AI provider or search engine is implemented in a separate directory under src/app/api, following a plug‑in–style structure.

- Env Variables (.env / env.tpl) feeding into the Serverless layer.
- Optional paths: static export (out/ directory) vs. dynamic mode.
- Custom patterns (e.g., Hook usage, Provider context for Theme/I18n).

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Client Layer
  subgraph "Client (Browser)" 
    direction TB
    AppRouter["Next.js App Router"]:::client
    ReactUI["React Components (UI Layer)"]:::client
    StateMgmt["State Management"]:::client
    LocalStorage["LocalStorage Utility"]:::client
    Editor["MilkdownEditor Component"]:::client
    AppRouter -->|renders| ReactUI
    ReactUI -->|reads/writes| StateMgmt
    StateMgmt -->|uses| LocalStorage
    ReactUI -->|embeds| Editor
  end

  %% Backend Layer
  subgraph "Next.js Serverless API" 
    direction TB
    Middleware["Middleware (Auth/Gateway)"]:::backend
    subgraph "AI Providers" 
      direction TB
      Anthropic["Anthropic API Route"]:::backend
      Deepseek["Deepseek API Route"]:::backend
      GoogleGemini["Google Gemini API Route"]:::backend
      Ollama["Ollama API Route"]:::backend
      OpenAI["OpenAI API Route"]:::backend
      OACompat["OpenAI-Compatible API Route"]:::backend
      OpenRouter["OpenRouter API Route"]:::backend
      XAI["XAI API Route"]:::backend
      Anthropic -->|proxies| Middleware
      Deepseek -->|proxies| Middleware
      GoogleGemini -->|proxies| Middleware
      Ollama -->|proxies| Middleware
      OpenAI -->|proxies| Middleware
      OACompat -->|proxies| Middleware
      OpenRouter -->|proxies| Middleware
      XAI -->|proxies| Middleware
    end
    subgraph "Search Providers" 
      direction TB
      Bocha["Bocha API Route"]:::backend
      Exa["Exa API Route"]:::backend
      Firecrawl["Firecrawl API Route"]:::backend
      SearxNG["SearxNG API Route"]:::backend
      Tavily["Tavily API Route"]:::backend
      Bocha -->|proxies| Middleware
      Exa -->|proxies| Middleware
      Firecrawl -->|proxies| Middleware
      SearxNG -->|proxies| Middleware
      Tavily -->|proxies| Middleware
    end
    Middleware -->|responds| ClientFetch["Fetch Calls from Client"]:::backend
    ClientFetch -->|calls| AppRouter
  end

  %% External Services
  subgraph "External Services"
    direction TB
    AIExt["AI Provider APIs"]:::external
    SearchExt["Web Search Engine APIs"]:::external
    Middleware -->|forwards AI requests| AIExt
    Middleware -->|forwards Search requests| SearchExt
  end

  %% Infrastructure
  subgraph "Deployment / Infrastructure"
    direction TB
    Vercel["Vercel Edge Functions"]:::infra
    Cloudflare["Cloudflare Workers"]:::infra
    Docker["Docker Container"]:::infra
    CDN["CDN / Static Hosting"]:::infra
    Vercel -->|deploys| AppRouter
    Cloudflare -->|deploys| Middleware
    Docker -->|runs| AppRouter
    CDN -->|serves| public["public/"]:::infra
  end

  %% Click Events
  click AppRouter "https://github.com/u14app/deep-research/tree/main/src/app"
  click ReactUI "https://github.com/u14app/deep-research/tree/main/src/components"
  click StateMgmt "https://github.com/u14app/deep-research/tree/main/src/store"
  click LocalStorage "https://github.com/u14app/deep-research/blob/main/src/utils/storage.ts"
  click Editor "https://github.com/u14app/deep-research/blob/main/src/components/MilkdownEditor/index.tsx"
  click Anthropic "https://github.com/u14app/deep-research/blob/main/src/app/api/ai/anthropic/[...slug]/route.ts"
  click Deepseek "https://github.com/u14app/deep-research/blob/main/src/app/api/ai/deepseek/[...slug]/route.ts"
  click GoogleGemini "https://github.com/u14app/deep-research/blob/main/src/app/api/ai/google/[...slug]/route.ts"
  click Ollama "https://github.com/u14app/deep-research/blob/main/src/app/api/ai/ollama/[...slug]/route.ts"
  click OpenAI "https://github.com/u14app/deep-research/blob/main/src/app/api/ai/openai/[...slug]/route.ts"
  click OACompat "https://github.com/u14app/deep-research/blob/main/src/app/api/ai/openaicompatible/[...slug]/route.ts"
  click OpenRouter "https://github.com/u14app/deep-research/blob/main/src/app/api/ai/openrouter/[...slug]/route.ts"
  click XAI "https://github.com/u14app/deep-research/blob/main/src/app/api/ai/xai/[...slug]/route.ts"
  click Bocha "https://github.com/u14app/deep-research/blob/main/src/app/api/search/bocha/[...slug]/route.ts"
  click Exa "https://github.com/u14app/deep-research/blob/main/src/app/api/search/exa/[...slug]/route.ts"
  click Firecrawl "https://github.com/u14app/deep-research/blob/main/src/app/api/search/firecrawl/[...slug]/route.ts"
  click SearxNG "https://github.com/u14app/deep-research/blob/main/src/app/api/search/searxng/[...slug]/route.ts"
  click Tavily "https://github.com/u14app/deep-research/blob/main/src/app/api/search/tavily/[...slug]/route.ts"
  click Middleware "https://github.com/u14app/deep-research/blob/main/src/middleware.ts"
  click AppRouter "https://github.com/u14app/deep-research/tree/main/src/app"
  click Layout "https://github.com/u14app/deep-research/blob/main/src/app/layout.tsx"
  click HomePage "https://github.com/u14app/deep-research/blob/main/src/app/page.tsx"
  click NotFound "https://github.com/u14app/deep-research/blob/main/src/app/not-found.tsx"
  click Hooks "https://github.com/u14app/deep-research/tree/main/src/hooks"
  click DataUtils "https://github.com/u14app/deep-research/tree/main/src/utils"
  click EnvTpl "https://github.com/u14app/deep-research/blob/main/env.tpl"
  click Vercel "https://github.com/u14app/deep-research/blob/main/vercel.json"
  click Cloudflare "https://github.com/u14app/deep-research/blob/main/wrangler.toml"
  click Docker "https://github.com/u14app/deep-research/tree/main/Dockerfile"
  click DockerCompose "https://github.com/u14app/deep-research/blob/main/docker-compose.yml"
  click public "https://github.com/u14app/deep-research/tree/main/public"
  click Tailwind "https://github.com/u14app/deep-research/blob/main/tailwind.config.ts"
  click GlobalsCSS "https://github.com/u14app/deep-research/blob/main/src/app/globals.css"
  click Constants "https://github.com/u14app/deep-research/tree/main/src/constants"
  click Locales "https://github.com/u14app/deep-research/tree/main/src/locales"

  %% Styles
  classDef client fill:#e0f7fa,stroke:#006064,color:#004d40
  classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
  classDef external fill:#fff3e0,stroke:#f57c00,color:#e65100
  classDef infra fill:#eceff1,stroke:#607d8b,color:#37474f
```
