# tinysuitehq/tinysearch architecture

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

- Interactive diagram: https://gitdiagram.com/tinysuitehq/tinysearch
- Repository: https://github.com/tinysuitehq/tinysearch

## Overview

TinySearch is a local web-retrieval service for agents: clients discover sources, fetch or interact with pages, and receive token-bounded original passages with source URLs. MCP and FastAPI adapt requests to the transport-neutral core; the core owns search and scrape operations. Scraping renders pages, applies URL safety and extraction, then ranks/chunks evidence. The README documents browser tools and datetime as additional MCP capabilities. Relationships shown from source are cited; some subsystem links rely on README capability descriptions because their implementations were not excerpted.

Main entry points: [`src/tinysearch/pipelines/scrape.py`](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/pipelines/scrape.py) (Scrape pipeline), [`src/tinysearch/core.py`](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/core.py) (Core operations), [`src/tinysearch/servers/mcp_server.py`](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/servers/mcp_server.py) (MCP server), [`src/tinysearch/servers/fastapi_server.py`](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/servers/fastapi_server.py) (FastAPI server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client interfaces"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_http["FastAPI server<br/>[fastapi_server.py]"]
  node_cli["CLI<br/>[cli.py]"]
  node_core["Core operations<br/>[core.py]"]
end

subgraph group_retrieval["Web retrieval"]
  node_search["Web search"]
  node_safety["URL safety"]
  node_crawl["Page crawler"]
  node_scrapesvc["Direct scraping<br/>[scrape_service.py]"]
  node_browser["Browser tools"]
end

subgraph group_evidence["Evidence processing"]
  node_scrape["Scrape pipeline<br/>[scrape.py]"]
  node_links["Link extraction"]
  node_chunking["Text chunking"]
  node_tokens["Token budgeting"]
  node_embedding["Local embeddings"]
  node_hybrid["Hybrid ranking"]
  node_results["Evidence results<br/>[results.py]"]
  node_prompts["Grounded prompts"]
end

subgraph group_runtime["Runtime support"]
  node_config["Public config<br/>[config.py]"]
  node_serverconfig["Server config"]
  node_datetime["Current datetime"]
  node_telemetry["Telemetry<br/>[telemetry.py]"]
  node_onnx["ONNX bundle"]
end

node_agent(("AI agent"))
node_backend["Search backend"]
node_pages["Web pages"]

node_agent -->|"requests tools"| node_mcp
node_agent -.->|"sends requests"| node_http
node_mcp -->|"dispatches operations"| node_core
node_http -->|"dispatches operations"| node_core
node_cli -->|"launches server"| node_mcp
node_core -->|"resolves settings"| node_config
node_core -->|"searches"| node_search
node_search -.->|"queries backend"| node_backend
node_core -->|"runs retrieval"| node_scrape
node_scrape -->|"validates URLs"| node_safety
node_scrape -->|"fetches pages"| node_crawl
node_crawl -.->|"renders pages"| node_pages
node_scrape -->|"extracts links"| node_links
node_scrape -->|"chunks text"| node_chunking
node_scrape -->|"budgets evidence"| node_tokens
node_scrape -->|"embeds passages"| node_embedding
node_scrape -->|"ranks passages"| node_hybrid
node_core -->|"scrapes URLs"| node_scrapesvc
node_scrape -.->|"returns evidence"| node_results
node_mcp -->|"exposes browser tools"| node_browser
node_mcp -.->|"exposes datetime tool"| node_datetime
node_mcp -->|"loads server settings"| node_serverconfig
node_serverconfig -->|"overrides config"| node_config
node_core -->|"prepares model bundle"| node_onnx
node_embedding -.->|"uses model bundle"| node_onnx
node_core -->|"records operations"| node_telemetry
node_scrape -.->|"builds grounded prompts"| node_prompts

click node_mcp "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/servers/mcp_server.py"
click node_http "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/servers/fastapi_server.py"
click node_cli "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/cli.py"
click node_core "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/core.py"
click node_config "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/config.py"
click node_serverconfig "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/tinysearch_config_service.py"
click node_search "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/web_search_service.py"
click node_safety "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/url_safety_service.py"
click node_scrape "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/pipelines/scrape.py"
click node_crawl "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/site_crawl_service.py"
click node_scrapesvc "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/scrape_service.py"
click node_links "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/link_extraction_service.py"
click node_chunking "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/text_chunking_service.py"
click node_tokens "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/token_counter_service.py"
click node_embedding "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/embedding_service.py"
click node_hybrid "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/hybrid_embed_search_service.py"
click node_results "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/results.py"
click node_browser "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/browser_tool_service.py"
click node_datetime "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/current_datetime_service.py"
click node_prompts "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/grounded_prompt_service.py"
click node_telemetry "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/telemetry.py"
click node_onnx "https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/onnx_bundle_service.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_mcp,node_http,node_cli,node_core toneBlue
class node_search,node_safety,node_crawl,node_scrapesvc,node_browser toneAmber
class node_scrape,node_links,node_chunking,node_tokens,node_embedding,node_hybrid,node_results,node_prompts toneMint
class node_config,node_serverconfig,node_datetime,node_telemetry,node_onnx toneRose
class node_agent,node_backend,node_pages toneIndigo
```

## Components

### Client interfaces

- [MCP server](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/servers/mcp_server.py): `src/tinysearch/servers/mcp_server.py`
- [FastAPI server](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/servers/fastapi_server.py): `src/tinysearch/servers/fastapi_server.py`
- [CLI](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/cli.py): `src/tinysearch/cli.py`
- [Core operations](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/core.py): `src/tinysearch/core.py`

### Web retrieval

- [Web search](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/web_search_service.py): `src/tinysearch/services/web_search_service.py`
- [URL safety](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/url_safety_service.py): `src/tinysearch/services/url_safety_service.py`
- [Page crawler](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/site_crawl_service.py): `src/tinysearch/services/site_crawl_service.py`
- [Direct scraping](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/scrape_service.py): `src/tinysearch/services/scrape_service.py`
- [Browser tools](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/browser_tool_service.py): `src/tinysearch/services/browser_tool_service.py`

### Evidence processing

- [Scrape pipeline](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/pipelines/scrape.py): `src/tinysearch/pipelines/scrape.py`
- [Link extraction](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/link_extraction_service.py): `src/tinysearch/services/link_extraction_service.py`
- [Text chunking](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/text_chunking_service.py): `src/tinysearch/services/text_chunking_service.py`
- [Token budgeting](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/token_counter_service.py): `src/tinysearch/services/token_counter_service.py`
- [Local embeddings](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/embedding_service.py): `src/tinysearch/services/embedding_service.py`
- [Hybrid ranking](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/hybrid_embed_search_service.py): `src/tinysearch/services/hybrid_embed_search_service.py`
- [Evidence results](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/results.py): `src/tinysearch/results.py`
- [Grounded prompts](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/grounded_prompt_service.py): `src/tinysearch/services/grounded_prompt_service.py`

### Runtime support

- [Public config](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/config.py): `src/tinysearch/config.py`
- [Server config](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/tinysearch_config_service.py): `src/tinysearch/services/tinysearch_config_service.py`
- [Current datetime](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/current_datetime_service.py): `src/tinysearch/services/current_datetime_service.py`
- [Telemetry](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/telemetry.py): `src/tinysearch/telemetry.py`
- [ONNX bundle](https://github.com/tinysuitehq/tinysearch/blob/main/src/tinysearch/services/onnx_bundle_service.py): `src/tinysearch/services/onnx_bundle_service.py`

### Other components

- **AI agent**
- **Search backend**
- **Web pages**

## Connections

- AI agent → MCP server: requests tools (evidence: `README.md`)
- AI agent → FastAPI server: sends requests (evidence: `README.md`)
- MCP server → Core operations: dispatches operations (evidence: `src/tinysearch/servers/mcp_server.py`)
- FastAPI server → Core operations: dispatches operations (evidence: `src/tinysearch/servers/fastapi_server.py`)
- CLI → MCP server: launches server (evidence: `src/tinysearch/cli.py`)
- Core operations → Public config: resolves settings (evidence: `src/tinysearch/core.py`)
- Core operations → Web search: searches (evidence: `src/tinysearch/core.py`)
- Web search → Search backend: queries backend
- Core operations → Scrape pipeline: runs retrieval (evidence: `src/tinysearch/core.py`)
- Scrape pipeline → URL safety: validates URLs (evidence: `src/tinysearch/pipelines/scrape.py`)
- Scrape pipeline → Page crawler: fetches pages (evidence: `src/tinysearch/pipelines/scrape.py`)
- Page crawler → Web pages: renders pages
- Scrape pipeline → Link extraction: extracts links (evidence: `src/tinysearch/pipelines/scrape.py`)
- Scrape pipeline → Text chunking: chunks text (evidence: `src/tinysearch/pipelines/scrape.py`)
- Scrape pipeline → Token budgeting: budgets evidence (evidence: `src/tinysearch/pipelines/scrape.py`)
- Scrape pipeline → Local embeddings: embeds passages (evidence: `src/tinysearch/pipelines/scrape.py`)
- Scrape pipeline → Hybrid ranking: ranks passages (evidence: `src/tinysearch/pipelines/scrape.py`)
- Core operations → Direct scraping: scrapes URLs (evidence: `src/tinysearch/core.py`)
- Scrape pipeline → Evidence results: returns evidence
- MCP server → Browser tools: exposes browser tools (evidence: `src/tinysearch/servers/mcp_server.py`)
- MCP server → Current datetime: exposes datetime tool (evidence: `README.md`)
- MCP server → Server config: loads server settings (evidence: `src/tinysearch/servers/mcp_server.py`)
- Server config → Public config: overrides config (evidence: `src/tinysearch/services/tinysearch_config_service.py`)
- Core operations → ONNX bundle: prepares model bundle (evidence: `src/tinysearch/core.py`)
- Local embeddings → ONNX bundle: uses model bundle (evidence: `src/tinysearch/services/onnx_bundle_service.py`)
- Core operations → Telemetry: records operations (evidence: `src/tinysearch/core.py`)
- Scrape pipeline → Grounded prompts: builds grounded prompts
