# benbusby/whoogle-search architecture

> Architecture diagram of the GitHub repository benbusby/whoogle-search, 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/benbusby/whoogle-search
- Repository: https://github.com/benbusby/whoogle-search

## Overview

Whoogle is a historically privacy-focused Google search proxy with a Flask web interface; the README now states that Google search no longer works and the project is inactive. Its principal workflow accepts a search request, prepares a query, fetches results through the legacy Google route or optional Custom Search API, cleans and formats results, and returns them to the user. The graph also preserves documented capabilities such as suggestions, bangs, image viewing, themes, and proxy support. Connections are limited to relationships shown by excerpts, SOURCE INDEX references, or README statements; some UI and route details were not sampled.

Main entry points: [`app/routes.py`](https://github.com/benbusby/whoogle-search/blob/main/app/routes.py) (HTTP Routes), [`app/utils/search.py`](https://github.com/benbusby/whoogle-search/blob/main/app/utils/search.py) (Search Orchestrator), [`app/request.py`](https://github.com/benbusby/whoogle-search/blob/main/app/request.py) (Google Request), [`app/static/js`](https://github.com/benbusby/whoogle-search/tree/main/app/static/js) (Browser Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Interface"]
  node_routes["HTTP Routes<br/>[routes.py]"]
  node_browser["Browser Interface"]
  node_templates["Search Views"]
end

subgraph group_search["Search Processing"]
  node_searchflow["Search Orchestrator<br/>[search.py]"]
  node_filter["Result Cleaner<br/>[filter.py]"]
  node_results["Result Formatting<br/>[results.py]"]
  node_bangs["Bang Resolver<br/>[bangs.py]"]
end

subgraph group_network["External Requests"]
  node_cse["Custom Search API<br/>[cse_client.py]"]
  node_request["Google Request<br/>[request.py]"]
  node_provider["HTTP Provider<br/>[provider.py]"]
  node_http["HTTP Client<br/>[http_client.py]"]
end

subgraph group_prefs["Preferences And Extras"]
  node_config["Search Preferences<br/>[config.py]"]
  node_session["User Session<br/>[session.py]"]
  node_ua["User-Agent Pool<br/>[ua_generator.py]"]
  node_widgets["Search Widgets<br/>[widgets.py]"]
end

node_user(("Search User"))
node_google(("Google Search"))

node_user -->|"submits query"| node_routes
node_routes -->|"dispatches search"| node_searchflow
node_routes -->|"loads preferences"| node_config
node_routes -->|"uses session"| node_session
node_routes -->|"resolves bangs"| node_bangs
node_routes -->|"uses widgets"| node_widgets
node_routes -->|"uses formatting"| node_results
node_routes -.->|"renders views"| node_templates
node_searchflow -->|"sends query"| node_request
node_searchflow -->|"cleans results"| node_filter
node_searchflow -->|"formats output"| node_results
node_searchflow -->|"calls API"| node_cse
node_searchflow -->|"reads preferences"| node_config
node_request -->|"gets client"| node_provider
node_request -->|"selects agent"| node_ua
node_provider -->|"uses client"| node_http
node_request -->|"queries Google"| node_google
node_cse -->|"queries API"| node_google
node_user -->|"uses interface"| node_browser
node_browser -.->|"requests suggestions"| node_routes

click node_routes "https://github.com/benbusby/whoogle-search/blob/main/app/routes.py"
click node_browser "https://github.com/benbusby/whoogle-search/tree/main/app/static/js"
click node_templates "https://github.com/benbusby/whoogle-search/tree/main/app/templates"
click node_searchflow "https://github.com/benbusby/whoogle-search/blob/main/app/utils/search.py"
click node_filter "https://github.com/benbusby/whoogle-search/blob/main/app/filter.py"
click node_results "https://github.com/benbusby/whoogle-search/blob/main/app/utils/results.py"
click node_bangs "https://github.com/benbusby/whoogle-search/blob/main/app/utils/bangs.py"
click node_cse "https://github.com/benbusby/whoogle-search/blob/main/app/services/cse_client.py"
click node_request "https://github.com/benbusby/whoogle-search/blob/main/app/request.py"
click node_provider "https://github.com/benbusby/whoogle-search/blob/main/app/services/provider.py"
click node_http "https://github.com/benbusby/whoogle-search/blob/main/app/services/http_client.py"
click node_config "https://github.com/benbusby/whoogle-search/blob/main/app/models/config.py"
click node_session "https://github.com/benbusby/whoogle-search/blob/main/app/utils/session.py"
click node_ua "https://github.com/benbusby/whoogle-search/blob/main/app/utils/ua_generator.py"
click node_widgets "https://github.com/benbusby/whoogle-search/blob/main/app/utils/widgets.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_routes,node_browser,node_templates,node_user toneBlue
class node_searchflow,node_filter,node_results,node_bangs toneAmber
class node_cse,node_request,node_provider,node_http toneMint
class node_config,node_session,node_ua,node_widgets toneRose
class node_google toneIndigo
```

## Components

### Web Interface

- [HTTP Routes](https://github.com/benbusby/whoogle-search/blob/main/app/routes.py): `app/routes.py`
- [Browser Interface](https://github.com/benbusby/whoogle-search/tree/main/app/static/js): `app/static/js`
- [Search Views](https://github.com/benbusby/whoogle-search/tree/main/app/templates): `app/templates`

### Search Processing

- [Search Orchestrator](https://github.com/benbusby/whoogle-search/blob/main/app/utils/search.py): `app/utils/search.py`
- [Result Cleaner](https://github.com/benbusby/whoogle-search/blob/main/app/filter.py): `app/filter.py`
- [Result Formatting](https://github.com/benbusby/whoogle-search/blob/main/app/utils/results.py): `app/utils/results.py`
- [Bang Resolver](https://github.com/benbusby/whoogle-search/blob/main/app/utils/bangs.py): `app/utils/bangs.py`

### External Requests

- [Custom Search API](https://github.com/benbusby/whoogle-search/blob/main/app/services/cse_client.py): `app/services/cse_client.py`
- [Google Request](https://github.com/benbusby/whoogle-search/blob/main/app/request.py): `app/request.py`
- [HTTP Provider](https://github.com/benbusby/whoogle-search/blob/main/app/services/provider.py): `app/services/provider.py`
- [HTTP Client](https://github.com/benbusby/whoogle-search/blob/main/app/services/http_client.py): `app/services/http_client.py`

### Preferences And Extras

- [Search Preferences](https://github.com/benbusby/whoogle-search/blob/main/app/models/config.py): `app/models/config.py`
- [User Session](https://github.com/benbusby/whoogle-search/blob/main/app/utils/session.py): `app/utils/session.py`
- [User-Agent Pool](https://github.com/benbusby/whoogle-search/blob/main/app/utils/ua_generator.py): `app/utils/ua_generator.py`
- [Search Widgets](https://github.com/benbusby/whoogle-search/blob/main/app/utils/widgets.py): `app/utils/widgets.py`

### Other components

- **Search User**
- **Google Search**

## Connections

- Search User → HTTP Routes: submits query (evidence: `README.md`)
- HTTP Routes → Search Orchestrator: dispatches search (evidence: `app/routes.py`)
- HTTP Routes → Search Preferences: loads preferences (evidence: `app/routes.py`)
- HTTP Routes → User Session: uses session (evidence: `app/routes.py`)
- HTTP Routes → Bang Resolver: resolves bangs (evidence: `app/routes.py`)
- HTTP Routes → Search Widgets: uses widgets (evidence: `app/routes.py`)
- HTTP Routes → Result Formatting: uses formatting (evidence: `app/routes.py`)
- HTTP Routes → Search Views: renders views
- Search Orchestrator → Google Request: sends query (evidence: `app/utils/search.py`)
- Search Orchestrator → Result Cleaner: cleans results (evidence: `app/utils/search.py`)
- Search Orchestrator → Result Formatting: formats output (evidence: `app/utils/search.py`)
- Search Orchestrator → Custom Search API: calls API (evidence: `app/utils/search.py`)
- Search Orchestrator → Search Preferences: reads preferences (evidence: `app/utils/search.py`)
- Google Request → HTTP Provider: gets client (evidence: `app/request.py`)
- Google Request → User-Agent Pool: selects agent (evidence: `app/request.py`)
- HTTP Provider → HTTP Client: uses client (evidence: `app/services/provider.py`)
- Google Request → Google Search: queries Google (evidence: `README.md`)
- Custom Search API → Google Search: queries API (evidence: `README.md`)
- Search User → Browser Interface: uses interface (evidence: `README.md`)
- Browser Interface → HTTP Routes: requests suggestions