# bddndndncnrhfjfjnf-droid/searchxng_scraper architecture

> Architecture diagram of the GitHub repository bddndndncnrhfjfjnf-droid/searchxng_scraper, 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/bddndndncnrhfjfjnf-droid/searchxng_scraper
- Repository: https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper

## Overview

SearXNG meta-search accepts queries through a Python API or CLI, discovers and ranks public instances, then races searches across them. Each instance search can use JSON or HTML and handle Anubis, limiter, or Portico challenges; results are returned to the caller and optionally saved as JSON. The graph preserves documented PDF and profile modes and the CLI’s optional update check. Some relationships are supported by README statements and the source index; unsampled internals are not inferred beyond those references.

Main entry points: [`searxng_scraper/race.py`](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/race.py) (Search race), [`searxng_scraper/api.py`](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/api.py) (Python API), [`searxng_scraper/cli.py`](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/cli.py) (CLI), [`searxng_scraper/instances.py`](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/instances.py) (Instance discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_library["Python API<br/>[api.py]"]
  node_compat["Import alias<br/>[searxng_search.py]"]
end

subgraph group_search["Search workflow"]
  node_engine["Search race<br/>[race.py]"]
  node_modes["PDF and profiles<br/>[race.py]"]
  node_parser["HTML parsing<br/>[htmlparse.py]"]
  node_directory["Instance discovery<br/>[instances.py]"]
end

subgraph group_challenges["Challenge handling"]
  node_anubis["Anubis solver<br/>[anubis.py]"]
  node_limiter["Limiter and Portico<br/>[limiter.py]"]
  node_pow["Proof of work<br/>[pow.py]"]
end

subgraph group_services["Shared services"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_state[("Instance and cookie cache<br/>[instances.py]")]
  node_reports["JSON reports<br/>[api.py]"]
  node_updater["Update checker<br/>[update.py]"]
end

node_user(("Search user"))
node_searspace["sear.space directory"]
node_instances["SearXNG instances"]
node_pypi["PyPI"]

node_user -->|"runs query"| node_cli
node_user -->|"calls search"| node_library
node_compat -->|"re-exports"| node_library
node_cli -->|"invokes search"| node_library
node_cli -->|"starts check"| node_updater
node_library -->|"executes query"| node_engine
node_engine -->|"gets candidates"| node_directory
node_directory -->|"fetches directory"| node_searspace
node_engine -->|"races requests"| node_instances
node_engine -->|"parses HTML"| node_parser
node_engine -->|"handles challenge"| node_anubis
node_engine -->|"handles limiter"| node_limiter
node_anubis -->|"solves proof"| node_pow
node_limiter -->|"solves proof"| node_pow
node_engine -->|"supports modes"| node_modes
node_directory -->|"reads and writes"| node_state
node_anubis -->|"caches cookies"| node_state
node_cli -->|"writes JSON"| node_reports
node_library -->|"saves results"| node_reports
node_updater -->|"checks release"| node_pypi
node_cli -->|"uses settings"| node_config
node_library -->|"uses settings"| node_config

click node_cli "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/cli.py"
click node_library "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/api.py"
click node_compat "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_search.py"
click node_engine "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/race.py"
click node_modes "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/race.py"
click node_parser "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/htmlparse.py"
click node_directory "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/instances.py"
click node_anubis "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/anubis.py"
click node_limiter "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/limiter.py"
click node_pow "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/pow.py"
click node_config "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/config.py"
click node_state "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/instances.py"
click node_reports "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/api.py"
click node_updater "https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/update.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_cli,node_library,node_compat,node_user toneBlue
class node_engine,node_modes,node_parser,node_directory toneAmber
class node_anubis,node_limiter,node_pow toneMint
class node_config,node_state,node_reports,node_updater toneRose
class node_searspace,node_instances,node_pypi toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/cli.py): `searxng_scraper/cli.py`
- [Python API](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/api.py): `searxng_scraper/api.py`
- [Import alias](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_search.py): `searxng_search.py`

### Search workflow

- [Search race](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/race.py): `searxng_scraper/race.py`
- [PDF and profiles](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/race.py): `searxng_scraper/race.py`
- [HTML parsing](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/htmlparse.py): `searxng_scraper/htmlparse.py`
- [Instance discovery](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/instances.py): `searxng_scraper/instances.py`

### Challenge handling

- [Anubis solver](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/anubis.py): `searxng_scraper/anubis.py`
- [Limiter and Portico](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/limiter.py): `searxng_scraper/limiter.py`
- [Proof of work](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/pow.py): `searxng_scraper/pow.py`

### Shared services

- [Runtime configuration](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/config.py): `searxng_scraper/config.py`
- [Instance and cookie cache](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/instances.py): `searxng_scraper/instances.py`
- [JSON reports](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/api.py): `searxng_scraper/api.py`
- [Update checker](https://github.com/bddndndncnrhfjfjnf-droid/searchxng_scraper/blob/main/searxng_scraper/update.py): `searxng_scraper/update.py`

### Other components

- **Search user**
- **sear.space directory**
- **SearXNG instances**
- **PyPI**

## Connections

- Search user → CLI: runs query (evidence: `README.md`)
- Search user → Python API: calls search (evidence: `README.md`)
- Import alias → Python API: re-exports (evidence: `searxng_search.py`)
- CLI → Python API: invokes search (evidence: `searxng_scraper/cli.py`)
- CLI → Update checker: starts check (evidence: `searxng_scraper/cli.py`)
- Python API → Search race: executes query (evidence: `searxng_scraper/api.py`)
- Search race → Instance discovery: gets candidates (evidence: `searxng_scraper/race.py`)
- Instance discovery → sear.space directory: fetches directory (evidence: `searxng_scraper/instances.py`)
- Search race → SearXNG instances: races requests (evidence: `README.md`)
- Search race → HTML parsing: parses HTML (evidence: `searxng_scraper/race.py`)
- Search race → Anubis solver: handles challenge (evidence: `searxng_scraper/race.py`)
- Search race → Limiter and Portico: handles limiter (evidence: `searxng_scraper/race.py`)
- Anubis solver → Proof of work: solves proof (evidence: `searxng_scraper/anubis.py`)
- Limiter and Portico → Proof of work: solves proof (evidence: `searxng_scraper/limiter.py`)
- Search race → PDF and profiles: supports modes (evidence: `README.md`)
- Instance discovery → Instance and cookie cache: reads and writes (evidence: `searxng_scraper/instances.py`)
- Anubis solver → Instance and cookie cache: caches cookies (evidence: `searxng_scraper/anubis.py`)
- CLI → JSON reports: writes JSON (evidence: `searxng_scraper/cli.py`)
- Python API → JSON reports: saves results (evidence: `searxng_scraper/api.py`)
- Update checker → PyPI: checks release (evidence: `searxng_scraper/update.py`)
- CLI → Runtime configuration: uses settings (evidence: `searxng_scraper/cli.py`)
- Python API → Runtime configuration: uses settings (evidence: `searxng_scraper/api.py`)
