# battam1111/omniseek architecture

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

- Interactive diagram: https://gitdiagram.com/battam1111/omniseek
- Repository: https://github.com/battam1111/omniseek

## Overview

OmniSeek is a self-hosted MCP server that gives an agent a unified way to search and inspect information across web, research, social, and login-walled sources. The main workflow is an MCP client invoking server tools; search fans out through source adapters, then normalizes and ranks results, while read, view, and transcribe handle documents and media. Research tools add identity, citation, enrichment, and collaboration analysis; recall adds persistent text/vector retrieval and an evidence graph, while sensors support standing queries. README tool descriptions and the source index establish the broad subsystems; some internal wiring is unsampled, so uncertain links are omitted.

Main entry points: [`src/omniseek/server.py`](https://github.com/battam1111/omniseek/blob/main/src/omniseek/server.py) (MCP tools), [`src/omniseek/core/fetcher.py`](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/fetcher.py) (Source router), [`src/omniseek/core/sources/api`](https://github.com/battam1111/omniseek/tree/main/src/omniseek/core/sources/api) (API adapters), [`src/omniseek/core/sources/walled`](https://github.com/battam1111/omniseek/tree/main/src/omniseek/core/sources/walled) (Login-walled adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_server["MCP tools<br/>[server.py]"]
end

subgraph group_retrieval["Search and sources"]
  node_fetcher["Source router<br/>[fetcher.py]"]
  node_api["API adapters"]
  node_scrape["Scrape adapters"]
  node_walled["Login-walled adapters"]
  node_normalize["Document normalization<br/>[normalize.py]"]
  node_rank["Deduplicate and rank<br/>[rank.py]"]
end

subgraph group_perception["Media and research"]
  node_docreader["Document reader<br/>[docreader.py]"]
  node_asr["Local transcription<br/>[asr.py]"]
  node_view["Image and video view<br/>[vframes.py]"]
  node_research["Research analysis<br/>[cartographer.py]"]
  node_enrich["Paper enrichment<br/>[enrich.py]"]
  node_relations["Identity and relations<br/>[relations.py]"]
end

subgraph group_memory["Recall and monitoring"]
  node_recall[("Recall search<br/>[store.py]")]
  node_graph[("Evidence graph<br/>[graph.py]")]
  node_writer["Recall ingestion<br/>[writer.py]"]
  node_sensor["Standing queries<br/>[sensor.py]"]
end

subgraph group_runtime["Runtime services"]
  node_cache[("Response cache<br/>[cache.py]")]
  node_http["HTTP and upstream controls<br/>[http.py]"]
  node_auth["Credential loader<br/>[auth.py]"]
end

node_agent(("Agent / client"))
node_upstream(("External sources"))

node_agent -->|"invokes tools"| node_server
node_server -->|"searches sources"| node_fetcher
node_fetcher -.->|"dispatches queries"| node_api
node_fetcher -.->|"dispatches queries"| node_scrape
node_fetcher -.->|"dispatches queries"| node_walled
node_api -.->|"requests data"| node_upstream
node_scrape -.->|"requests data"| node_upstream
node_walled -.->|"requests data"| node_upstream
node_fetcher -->|"normalizes results"| node_normalize
node_fetcher -->|"ranks results"| node_rank
node_server -->|"reads documents"| node_docreader
node_server -->|"transcribes media"| node_asr
node_server -->|"views media"| node_view
node_server -->|"maps citations"| node_research
node_server -->|"enriches papers"| node_enrich
node_server -->|"resolves researchers"| node_relations
node_server -->|"recalls documents"| node_recall
node_server -->|"queries graph"| node_graph
node_writer -->|"writes index"| node_recall
node_server -.->|"runs monitoring"| node_sensor
node_fetcher -->|"reads and writes"| node_cache
node_fetcher -.->|"makes requests"| node_http
node_api -.->|"loads credentials"| node_auth
node_walled -.->|"loads credentials"| node_auth

click node_server "https://github.com/battam1111/omniseek/blob/main/src/omniseek/server.py"
click node_fetcher "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/fetcher.py"
click node_api "https://github.com/battam1111/omniseek/tree/main/src/omniseek/core/sources/api"
click node_scrape "https://github.com/battam1111/omniseek/tree/main/src/omniseek/core/sources/scrape"
click node_walled "https://github.com/battam1111/omniseek/tree/main/src/omniseek/core/sources/walled"
click node_normalize "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/normalize.py"
click node_rank "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/rank.py"
click node_docreader "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/docreader.py"
click node_asr "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/asr.py"
click node_view "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/vframes.py"
click node_research "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/cartographer.py"
click node_enrich "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/enrich.py"
click node_relations "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/relations.py"
click node_recall "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/recall/store.py"
click node_graph "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/recall/graph.py"
click node_writer "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/recall/writer.py"
click node_sensor "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/sensor.py"
click node_cache "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/cache.py"
click node_http "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/http.py"
click node_auth "https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/auth.py"

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_server,node_agent toneBlue
class node_fetcher,node_api,node_scrape,node_walled,node_normalize,node_rank toneAmber
class node_docreader,node_asr,node_view,node_research,node_enrich,node_relations toneMint
class node_recall,node_graph,node_writer,node_sensor toneRose
class node_cache,node_http,node_auth,node_upstream toneIndigo
```

## Components

### MCP interface

- [MCP tools](https://github.com/battam1111/omniseek/blob/main/src/omniseek/server.py): `src/omniseek/server.py`

### Search and sources

- [Source router](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/fetcher.py): `src/omniseek/core/fetcher.py`
- [API adapters](https://github.com/battam1111/omniseek/tree/main/src/omniseek/core/sources/api): `src/omniseek/core/sources/api`
- [Scrape adapters](https://github.com/battam1111/omniseek/tree/main/src/omniseek/core/sources/scrape): `src/omniseek/core/sources/scrape`
- [Login-walled adapters](https://github.com/battam1111/omniseek/tree/main/src/omniseek/core/sources/walled): `src/omniseek/core/sources/walled`
- [Document normalization](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/normalize.py): `src/omniseek/core/normalize.py`
- [Deduplicate and rank](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/rank.py): `src/omniseek/core/rank.py`

### Media and research

- [Document reader](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/docreader.py): `src/omniseek/core/docreader.py`
- [Local transcription](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/asr.py): `src/omniseek/core/asr.py`
- [Image and video view](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/vframes.py): `src/omniseek/core/vframes.py`
- [Research analysis](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/cartographer.py): `src/omniseek/core/cartographer.py`
- [Paper enrichment](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/enrich.py): `src/omniseek/core/enrich.py`
- [Identity and relations](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/relations.py): `src/omniseek/core/relations.py`

### Recall and monitoring

- [Recall search](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/recall/store.py): `src/omniseek/core/recall/store.py`
- [Evidence graph](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/recall/graph.py): `src/omniseek/core/recall/graph.py`
- [Recall ingestion](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/recall/writer.py): `src/omniseek/core/recall/writer.py`
- [Standing queries](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/sensor.py): `src/omniseek/core/sensor.py`

### Runtime services

- [Response cache](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/cache.py): `src/omniseek/core/cache.py`
- [HTTP and upstream controls](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/http.py): `src/omniseek/core/http.py`
- [Credential loader](https://github.com/battam1111/omniseek/blob/main/src/omniseek/core/auth.py): `src/omniseek/core/auth.py`

### Other components

- **Agent / client**
- **External sources**

## Connections

- Agent / client → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → Source router: searches sources (evidence: `src/omniseek/server.py`)
- Source router → API adapters: dispatches queries (evidence: `src/omniseek/core/sources/api/openrouter_rankings_source.py`)
- Source router → Scrape adapters: dispatches queries (evidence: `src/omniseek/core/fetcher.py`)
- Source router → Login-walled adapters: dispatches queries (evidence: `src/omniseek/core/sources/walled/xiaohongshu_cn_source.py`)
- API adapters → External sources: requests data
- Scrape adapters → External sources: requests data
- Login-walled adapters → External sources: requests data
- Source router → Document normalization: normalizes results (evidence: `src/omniseek/core/fetcher.py`)
- Source router → Deduplicate and rank: ranks results (evidence: `src/omniseek/core/fetcher.py`)
- MCP tools → Document reader: reads documents (evidence: `README.md`)
- MCP tools → Local transcription: transcribes media (evidence: `README.md`)
- MCP tools → Image and video view: views media (evidence: `README.md`)
- MCP tools → Research analysis: maps citations (evidence: `README.md`)
- MCP tools → Paper enrichment: enriches papers (evidence: `README.md`)
- MCP tools → Identity and relations: resolves researchers (evidence: `README.md`)
- MCP tools → Recall search: recalls documents (evidence: `README.md`)
- MCP tools → Evidence graph: queries graph (evidence: `README.md`)
- Recall ingestion → Recall search: writes index (evidence: `src/omniseek/core/recall/writer.py`)
- MCP tools → Standing queries: runs monitoring (evidence: `src/omniseek/server.py`)
- Source router → Response cache: reads and writes (evidence: `src/omniseek/core/fetcher.py`)
- Source router → HTTP and upstream controls: makes requests
- API adapters → Credential loader: loads credentials (evidence: `src/omniseek/core/sources/api/openreview_source.py`)
- Login-walled adapters → Credential loader: loads credentials
