# fatwang2/search2ai architecture

> Architecture diagram of the GitHub repository fatwang2/search2ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fatwang2/search2ai
- Repository: https://github.com/fatwang2/search2ai

## Overview

search2ai is a self-hosted, Perplexity-compatible search gateway: clients submit search, news, or crawl requests and receive normalized results with provider identity and fallback warnings. Its library core selects configured providers, retries along operation-specific chains, optionally enriches results with crawled content, and caches responses. Hono exposes HTTP and MCP interfaces; an optional legacy chat proxy injects gateway tools into OpenAI-compatible chat requests. Provider implementations and several HTTP/MCP relationships are shown in the supplied source index and excerpts; edges for documented but unsampled deployment capabilities are omitted.

Main entry points: [`src/core/gateway.ts`](https://github.com/fatwang2/search2ai/blob/main/src/core/gateway.ts) (Gateway operations), [`src/server/app.ts`](https://github.com/fatwang2/search2ai/blob/main/src/server/app.ts) (HTTP routes), [`src/core/providers/index.ts`](https://github.com/fatwang2/search2ai/blob/main/src/core/providers/index.ts) (Provider registry), [`src/core/http.ts`](https://github.com/fatwang2/search2ai/blob/main/src/core/http.ts) (Provider HTTP helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client interfaces"]
  node_hono["Hono assembly<br/>[hono.ts]"]
  node_http["HTTP routes<br/>[app.ts]"]
  node_mcp["MCP tools<br/>[server.ts]"]
  node_openapi["OpenAPI document<br/>[openapi.ts]"]
end

subgraph group_gateway["Gateway core"]
  node_gateway["Gateway operations<br/>[gateway.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_fallback["Fallback chain<br/>[fallback.ts]"]
  node_cache[("Result cache<br/>[cache.ts]")]
  node_schemas["Request schemas<br/>[schema.ts]"]
end

subgraph group_providers["Search providers"]
  node_provider_registry["Provider registry<br/>[index.ts]"]
  node_search1api["Search1API<br/>[search1api.ts]"]
  node_tavily["Tavily<br/>[tavily.ts]"]
  node_exa["Exa<br/>[exa.ts]"]
  node_other_search["Other search backends"]
  node_crawl_backends["Crawl backends"]
  node_provider_http["Provider HTTP helpers<br/>[http.ts]"]
end

subgraph group_chat["Chat compatibility"]
  node_upstream["Chat upstream<br/>[upstream.ts]"]
  node_chat_proxy["Tool-using chat proxy<br/>[proxy.ts]"]
end

node_clients(("API clients"))
node_model_service(("OpenAI-compatible model"))

node_clients -->|"calls"| node_hono
node_hono -->|"builds config"| node_config
node_hono -->|"creates"| node_gateway
node_hono -->|"assembles"| node_http
node_http -->|"routes requests"| node_gateway
node_http -->|"validates"| node_schemas
node_http -->|"connects transport"| node_mcp
node_http -->|"serves document"| node_openapi
node_mcp -->|"invokes tools"| node_gateway
node_gateway -->|"uses settings"| node_config
node_gateway -->|"creates providers"| node_provider_registry
node_gateway -->|"runs operations"| node_fallback
node_gateway -->|"reads writes"| node_cache
node_provider_registry -->|"registers"| node_search1api
node_provider_registry -->|"registers"| node_tavily
node_provider_registry -->|"registers"| node_exa
node_provider_registry -->|"registers"| node_other_search
node_provider_registry -->|"registers"| node_crawl_backends
node_search1api -->|"uses"| node_provider_http
node_tavily -->|"uses"| node_provider_http
node_exa -->|"uses"| node_provider_http
node_other_search -->|"uses"| node_provider_http
node_crawl_backends -->|"uses"| node_provider_http
node_clients -.->|"submits chat"| node_chat_proxy
node_http -->|"routes completions"| node_chat_proxy
node_chat_proxy -->|"executes tools"| node_gateway
node_chat_proxy -->|"calls completions"| node_upstream
node_http -->|"forwards requests"| node_upstream
node_upstream -->|"sends requests"| node_model_service

click node_hono "https://github.com/fatwang2/search2ai/blob/main/src/hono.ts"
click node_http "https://github.com/fatwang2/search2ai/blob/main/src/server/app.ts"
click node_mcp "https://github.com/fatwang2/search2ai/blob/main/src/mcp/server.ts"
click node_openapi "https://github.com/fatwang2/search2ai/blob/main/src/server/openapi.ts"
click node_gateway "https://github.com/fatwang2/search2ai/blob/main/src/core/gateway.ts"
click node_config "https://github.com/fatwang2/search2ai/blob/main/src/core/config.ts"
click node_fallback "https://github.com/fatwang2/search2ai/blob/main/src/core/fallback.ts"
click node_cache "https://github.com/fatwang2/search2ai/blob/main/src/core/cache.ts"
click node_schemas "https://github.com/fatwang2/search2ai/blob/main/src/core/schema.ts"
click node_provider_registry "https://github.com/fatwang2/search2ai/blob/main/src/core/providers/index.ts"
click node_search1api "https://github.com/fatwang2/search2ai/blob/main/src/core/providers/search1api.ts"
click node_tavily "https://github.com/fatwang2/search2ai/blob/main/src/core/providers/tavily.ts"
click node_exa "https://github.com/fatwang2/search2ai/blob/main/src/core/providers/exa.ts"
click node_other_search "https://github.com/fatwang2/search2ai/tree/main/src/core/providers"
click node_crawl_backends "https://github.com/fatwang2/search2ai/tree/main/src/core/providers"
click node_provider_http "https://github.com/fatwang2/search2ai/blob/main/src/core/http.ts"
click node_upstream "https://github.com/fatwang2/search2ai/blob/main/src/chat/upstream.ts"
click node_chat_proxy "https://github.com/fatwang2/search2ai/blob/main/src/chat/proxy.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hono,node_http,node_mcp,node_openapi,node_clients toneBlue
class node_gateway,node_config,node_fallback,node_cache,node_schemas toneAmber
class node_provider_registry,node_search1api,node_tavily,node_exa,node_other_search,node_crawl_backends,node_provider_http toneMint
class node_upstream,node_chat_proxy toneRose
class node_model_service toneIndigo
```

## Components

### Client interfaces

- [Hono assembly](https://github.com/fatwang2/search2ai/blob/main/src/hono.ts): `src/hono.ts`
- [HTTP routes](https://github.com/fatwang2/search2ai/blob/main/src/server/app.ts): `src/server/app.ts`
- [MCP tools](https://github.com/fatwang2/search2ai/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [OpenAPI document](https://github.com/fatwang2/search2ai/blob/main/src/server/openapi.ts): `src/server/openapi.ts`

### Gateway core

- [Gateway operations](https://github.com/fatwang2/search2ai/blob/main/src/core/gateway.ts): `src/core/gateway.ts`
- [Configuration](https://github.com/fatwang2/search2ai/blob/main/src/core/config.ts): `src/core/config.ts`
- [Fallback chain](https://github.com/fatwang2/search2ai/blob/main/src/core/fallback.ts): `src/core/fallback.ts`
- [Result cache](https://github.com/fatwang2/search2ai/blob/main/src/core/cache.ts): `src/core/cache.ts`
- [Request schemas](https://github.com/fatwang2/search2ai/blob/main/src/core/schema.ts): `src/core/schema.ts`

### Search providers

- [Provider registry](https://github.com/fatwang2/search2ai/blob/main/src/core/providers/index.ts): `src/core/providers/index.ts`
- [Search1API](https://github.com/fatwang2/search2ai/blob/main/src/core/providers/search1api.ts): `src/core/providers/search1api.ts`
- [Tavily](https://github.com/fatwang2/search2ai/blob/main/src/core/providers/tavily.ts): `src/core/providers/tavily.ts`
- [Exa](https://github.com/fatwang2/search2ai/blob/main/src/core/providers/exa.ts): `src/core/providers/exa.ts`
- [Other search backends](https://github.com/fatwang2/search2ai/tree/main/src/core/providers): `src/core/providers`
- [Crawl backends](https://github.com/fatwang2/search2ai/tree/main/src/core/providers): `src/core/providers`
- [Provider HTTP helpers](https://github.com/fatwang2/search2ai/blob/main/src/core/http.ts): `src/core/http.ts`

### Chat compatibility

- [Chat upstream](https://github.com/fatwang2/search2ai/blob/main/src/chat/upstream.ts): `src/chat/upstream.ts`
- [Tool-using chat proxy](https://github.com/fatwang2/search2ai/blob/main/src/chat/proxy.ts): `src/chat/proxy.ts`

### Other components

- **API clients**
- **OpenAI-compatible model**

## Connections

- API clients → Hono assembly: calls (evidence: `README.md`)
- Hono assembly → Configuration: builds config (evidence: `src/hono.ts`)
- Hono assembly → Gateway operations: creates (evidence: `src/hono.ts`)
- Hono assembly → HTTP routes: assembles (evidence: `src/hono.ts`)
- HTTP routes → Gateway operations: routes requests (evidence: `src/server/app.ts`)
- HTTP routes → Request schemas: validates (evidence: `src/server/app.ts`)
- HTTP routes → MCP tools: connects transport (evidence: `src/server/app.ts`)
- HTTP routes → OpenAPI document: serves document (evidence: `src/server/app.ts`)
- MCP tools → Gateway operations: invokes tools (evidence: `src/mcp/server.ts`)
- Gateway operations → Configuration: uses settings (evidence: `src/core/gateway.ts`)
- Gateway operations → Provider registry: creates providers (evidence: `src/core/gateway.ts`)
- Gateway operations → Fallback chain: runs operations (evidence: `src/core/gateway.ts`)
- Gateway operations → Result cache: reads writes (evidence: `src/core/gateway.ts`)
- Provider registry → Search1API: registers (evidence: `src/core/providers/index.ts`)
- Provider registry → Tavily: registers (evidence: `src/core/providers/index.ts`)
- Provider registry → Exa: registers (evidence: `src/core/providers/index.ts`)
- Provider registry → Other search backends: registers (evidence: `src/core/providers/index.ts`)
- Provider registry → Crawl backends: registers (evidence: `src/core/providers/index.ts`)
- Search1API → Provider HTTP helpers: uses (evidence: `src/core/providers/search1api.ts`)
- Tavily → Provider HTTP helpers: uses (evidence: `src/core/providers/tavily.ts`)
- Exa → Provider HTTP helpers: uses (evidence: `src/core/providers/exa.ts`)
- Other search backends → Provider HTTP helpers: uses (evidence: `src/core/providers/index.ts`)
- Crawl backends → Provider HTTP helpers: uses (evidence: `src/core/providers/index.ts`)
- API clients → Tool-using chat proxy: submits chat (evidence: `README.md`)
- HTTP routes → Tool-using chat proxy: routes completions (evidence: `src/server/app.ts`)
- Tool-using chat proxy → Gateway operations: executes tools (evidence: `src/chat/proxy.ts`)
- Tool-using chat proxy → Chat upstream: calls completions (evidence: `src/chat/proxy.ts`)
- HTTP routes → Chat upstream: forwards requests (evidence: `src/server/app.ts`)
- Chat upstream → OpenAI-compatible model: sends requests (evidence: `src/chat/upstream.ts`)