# kerberos255/searxng-windows architecture

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

- Interactive diagram: https://gitdiagram.com/kerberos255/searxng-windows
- Repository: https://github.com/kerberos255/searxng-windows

## Overview

This repository packages a native Windows SearXNG installer and operations toolkit, with an optional API-first search gateway. The main workflow is a client querying local SearXNG directly or, when enabled, the Broker; the Broker tries configured API providers in priority order, then falls back to free SearXNG engines. The graph also shows installation/configuration, provider health state, and the SearXNG adapter. Broker internals are sampled; lifecycle scripts and upstream SearXNG behavior are represented from README documentation, not inspected source.

Main entry points: [`api_pool/app.py`](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/app.py) (Search Broker), [`api_pool/providers/base.py`](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/base.py) (Provider Interface), [`api_pool/providers/parallel.py`](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/parallel.py) (Parallel Search), [`api_pool/providers/tavily.py`](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/tavily.py) (Tavily Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ops["Windows Operations"]
  node_installer["Install Toolkit<br/>[install.ps1]"]
  node_launcher["Service Launcher<br/>[start.ps1]"]
  node_health["Health Check<br/>[check.ps1]"]
  node_updater["Source Updater<br/>[update.ps1]"]
  node_localconfig["Local Configuration"]
end

subgraph group_search["SearXNG Search"]
  node_searxng["SearXNG Service"]
  node_adapter["API Pool Engine Adapter<br/>[api_pool.py]"]
  node_timepatch["Date-Range Compatibility"]
  node_freeengines["Free SearXNG Engines"]
end

subgraph group_broker["API Pool Broker"]
  node_broker["Search Broker<br/>[app.py]"]
  node_brokerconfig["Broker Configuration<br/>[config.py]"]
  node_providerstate[("Provider State<br/>[state.py]")]
end

subgraph group_providers["Search Providers"]
  node_providerbase["Provider Interface<br/>[base.py]"]
  node_parallel["Parallel Search<br/>[parallel.py]"]
  node_tavily["Tavily Search<br/>[tavily.py]"]
  node_brave["Brave Search<br/>[brave.py]"]
  node_firecrawl["Firecrawl Search<br/>[firecrawl.py]"]
end

node_user(("Search Client"))
node_upstream["Search Upstreams"]

node_installer -->|"installs"| node_searxng
node_installer -->|"generates"| node_localconfig
node_launcher -->|"starts"| node_searxng
node_launcher -->|"starts if enabled"| node_broker
node_health -->|"checks health"| node_searxng
node_updater -->|"updates source"| node_searxng
node_user -->|"searches port 8888"| node_searxng
node_user -->|"searches port 8890"| node_broker
node_searxng -->|"dispatches search"| node_adapter
node_adapter -->|"posts query"| node_broker
node_broker -->|"reads settings"| node_brokerconfig
node_broker -->|"reads and updates"| node_providerstate
node_broker -->|"dispatches by priority"| node_parallel
node_broker -->|"dispatches by priority"| node_tavily
node_broker -->|"dispatches by priority"| node_brave
node_broker -->|"dispatches by priority"| node_firecrawl
node_broker -->|"falls back when needed"| node_freeengines
node_freeengines -->|"queries engines"| node_searxng
node_parallel -->|"uses shared client"| node_providerbase
node_tavily -->|"uses shared client"| node_providerbase
node_brave -->|"uses shared client"| node_providerbase
node_firecrawl -->|"uses shared client"| node_providerbase
node_parallel -->|"requests search"| node_upstream
node_tavily -->|"requests search"| node_upstream
node_brave -->|"requests search"| node_upstream
node_firecrawl -->|"requests search"| node_upstream
node_timepatch -->|"patches date filtering"| node_searxng

click node_installer "https://github.com/kerberos255/searxng-windows/blob/main/scripts/install.ps1"
click node_launcher "https://github.com/kerberos255/searxng-windows/blob/main/scripts/start.ps1"
click node_health "https://github.com/kerberos255/searxng-windows/blob/main/scripts/check.ps1"
click node_updater "https://github.com/kerberos255/searxng-windows/blob/main/scripts/update.ps1"
click node_localconfig "https://github.com/kerberos255/searxng-windows/blob/main/config/settings.example.yml"
click node_adapter "https://github.com/kerberos255/searxng-windows/blob/main/patches/api_pool.py"
click node_timepatch "https://github.com/kerberos255/searxng-windows/blob/main/scripts/patch_time_range_engines.py"
click node_broker "https://github.com/kerberos255/searxng-windows/blob/main/api_pool/app.py"
click node_brokerconfig "https://github.com/kerberos255/searxng-windows/blob/main/api_pool/config.py"
click node_providerstate "https://github.com/kerberos255/searxng-windows/blob/main/api_pool/state.py"
click node_providerbase "https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/base.py"
click node_parallel "https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/parallel.py"
click node_tavily "https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/tavily.py"
click node_brave "https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/brave.py"
click node_firecrawl "https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/firecrawl.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_installer,node_launcher,node_health,node_updater,node_localconfig,node_user toneBlue
class node_searxng,node_adapter,node_timepatch,node_freeengines toneAmber
class node_broker,node_brokerconfig,node_providerstate toneMint
class node_providerbase,node_parallel,node_tavily,node_brave,node_firecrawl toneRose
class node_upstream toneIndigo
```

## Components

### Windows Operations

- [Install Toolkit](https://github.com/kerberos255/searxng-windows/blob/main/scripts/install.ps1): `scripts/install.ps1`
- [Service Launcher](https://github.com/kerberos255/searxng-windows/blob/main/scripts/start.ps1): `scripts/start.ps1`
- [Health Check](https://github.com/kerberos255/searxng-windows/blob/main/scripts/check.ps1): `scripts/check.ps1`
- [Source Updater](https://github.com/kerberos255/searxng-windows/blob/main/scripts/update.ps1): `scripts/update.ps1`
- [Local Configuration](https://github.com/kerberos255/searxng-windows/blob/main/config/settings.example.yml): `config/settings.example.yml`

### SearXNG Search

- **SearXNG Service**
- [API Pool Engine Adapter](https://github.com/kerberos255/searxng-windows/blob/main/patches/api_pool.py): `patches/api_pool.py`
- [Date-Range Compatibility](https://github.com/kerberos255/searxng-windows/blob/main/scripts/patch_time_range_engines.py): `scripts/patch_time_range_engines.py`
- **Free SearXNG Engines**

### API Pool Broker

- [Search Broker](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/app.py): `api_pool/app.py`
- [Broker Configuration](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/config.py): `api_pool/config.py`
- [Provider State](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/state.py): `api_pool/state.py`

### Search Providers

- [Provider Interface](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/base.py): `api_pool/providers/base.py`
- [Parallel Search](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/parallel.py): `api_pool/providers/parallel.py`
- [Tavily Search](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/tavily.py): `api_pool/providers/tavily.py`
- [Brave Search](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/brave.py): `api_pool/providers/brave.py`
- [Firecrawl Search](https://github.com/kerberos255/searxng-windows/blob/main/api_pool/providers/firecrawl.py): `api_pool/providers/firecrawl.py`

### Other components

- **Search Client**
- **Search Upstreams**

## Connections

- Install Toolkit → SearXNG Service: installs (evidence: `README.md`)
- Install Toolkit → Local Configuration: generates (evidence: `README.md`)
- Service Launcher → SearXNG Service: starts (evidence: `README.md`)
- Service Launcher → Search Broker: starts if enabled (evidence: `README.md`)
- Health Check → SearXNG Service: checks health (evidence: `README.md`)
- Source Updater → SearXNG Service: updates source (evidence: `README.md`)
- Search Client → SearXNG Service: searches port 8888 (evidence: `README.md`)
- Search Client → Search Broker: searches port 8890 (evidence: `README.md`)
- SearXNG Service → API Pool Engine Adapter: dispatches search (evidence: `patches/api_pool.py`)
- API Pool Engine Adapter → Search Broker: posts query (evidence: `patches/api_pool.py`)
- Search Broker → Broker Configuration: reads settings (evidence: `api_pool/app.py`)
- Search Broker → Provider State: reads and updates (evidence: `api_pool/app.py`)
- Search Broker → Parallel Search: dispatches by priority (evidence: `README.md`)
- Search Broker → Tavily Search: dispatches by priority (evidence: `README.md`)
- Search Broker → Brave Search: dispatches by priority (evidence: `README.md`)
- Search Broker → Firecrawl Search: dispatches by priority (evidence: `README.md`)
- Search Broker → Free SearXNG Engines: falls back when needed (evidence: `README.md`)
- Free SearXNG Engines → SearXNG Service: queries engines (evidence: `README.md`)
- Parallel Search → Provider Interface: uses shared client (evidence: `api_pool/providers/parallel.py`)
- Tavily Search → Provider Interface: uses shared client (evidence: `api_pool/providers/tavily.py`)
- Brave Search → Provider Interface: uses shared client (evidence: `api_pool/providers/brave.py`)
- Firecrawl Search → Provider Interface: uses shared client (evidence: `api_pool/providers/firecrawl.py`)
- Parallel Search → Search Upstreams: requests search (evidence: `api_pool/providers/parallel.py`)
- Tavily Search → Search Upstreams: requests search (evidence: `api_pool/providers/tavily.py`)
- Brave Search → Search Upstreams: requests search (evidence: `api_pool/providers/brave.py`)
- Firecrawl Search → Search Upstreams: requests search (evidence: `api_pool/providers/firecrawl.py`)
- Date-Range Compatibility → SearXNG Service: patches date filtering (evidence: `scripts/patch_time_range_engines.py`)
