# uwavo/goofish-live-search architecture

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

- Interactive diagram: https://gitdiagram.com/uwavo/goofish-live-search
- Repository: https://github.com/uwavo/goofish-live-search

## Overview

Goofish Live Search is a local web dashboard for finding public Goofish listings without login. The user submits a query and filters in the frontend; the API translates it, discovers indexed listings through Bing using a browser context, filters and caches results, then returns cards for browsing. Item-page hydration and DOM/API extraction are also documented capabilities, though the sampled search route does not invoke them. Browser lifecycle, normalization, adaptive throttling, and SQLite caching form the internal runtime layer. The graph follows relationships visible in excerpts or the README; undocumented connections are omitted.

Main entry points: [`backend/routes.py`](https://github.com/uwavo/goofish-live-search/blob/master/backend/routes.py) (Search endpoints), [`backend/browser_engine.py`](https://github.com/uwavo/goofish-live-search/blob/master/backend/browser_engine.py) (Browser engine and hydration), [`backend/discovery.py`](https://github.com/uwavo/goofish-live-search/blob/master/backend/discovery.py) (Indexed listing discovery), [`frontend/app.js`](https://github.com/uwavo/goofish-live-search/blob/master/frontend/app.js) (Search and results UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Search dashboard"]
  node_frontend["Search and results UI<br/>[app.js]"]
end

subgraph group_api["Search API"]
  node_fastapi["Web application<br/>[main.py]"]
  node_routes["Search endpoints<br/>[routes.py]"]
end

subgraph group_discovery["Listing discovery"]
  node_bing["Bing search"]
  node_discovery["Indexed listing discovery<br/>[discovery.py]"]
end

subgraph group_runtime["Browser runtime"]
  node_browser["Browser engine and hydration<br/>[browser_engine.py]"]
end

subgraph group_support["Search support"]
  node_translation["Query translation<br/>[translator.py]"]
  node_normalizer["Listing normalization and filters<br/>[normalizer.py]"]
  node_limiter["Adaptive rate limiter<br/>[rate_limiter.py]"]
  node_cache[("SQLite result cache<br/>[cache.py]")]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_visitor(("Dashboard user"))
node_goofish["Goofish listings"]

node_visitor -->|"searches listings"| node_frontend
node_frontend -->|"requests search"| node_routes
node_fastapi -->|"mounts API"| node_routes
node_fastapi -->|"starts and closes"| node_browser
node_routes -->|"translates query"| node_translation
node_routes -->|"reads and writes"| node_cache
node_routes -->|"filters prices"| node_normalizer
node_routes -->|"gets context"| node_browser
node_routes -->|"discovers listings"| node_discovery
node_discovery -->|"searches indexes"| node_bing
node_discovery -->|"resolves listing pages"| node_goofish
node_browser -->|"visits item pages"| node_goofish
node_browser -->|"normalizes details"| node_normalizer
node_browser -->|"throttles hydration"| node_limiter
node_browser -->|"uses settings"| node_config
node_cache -->|"uses cache settings"| node_config
node_limiter -->|"uses rate setting"| node_config
node_translation -.->|"supports Chinese queries"| node_bing
node_routes -->|"returns listings"| node_frontend

click node_frontend "https://github.com/uwavo/goofish-live-search/blob/master/frontend/app.js"
click node_fastapi "https://github.com/uwavo/goofish-live-search/blob/master/backend/main.py"
click node_routes "https://github.com/uwavo/goofish-live-search/blob/master/backend/routes.py"
click node_translation "https://github.com/uwavo/goofish-live-search/blob/master/backend/translator.py"
click node_discovery "https://github.com/uwavo/goofish-live-search/blob/master/backend/discovery.py"
click node_browser "https://github.com/uwavo/goofish-live-search/blob/master/backend/browser_engine.py"
click node_normalizer "https://github.com/uwavo/goofish-live-search/blob/master/backend/normalizer.py"
click node_limiter "https://github.com/uwavo/goofish-live-search/blob/master/backend/rate_limiter.py"
click node_cache "https://github.com/uwavo/goofish-live-search/blob/master/backend/cache.py"
click node_config "https://github.com/uwavo/goofish-live-search/blob/master/backend/config.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_frontend,node_visitor toneBlue
class node_fastapi,node_routes toneAmber
class node_bing,node_discovery toneMint
class node_browser toneRose
class node_translation,node_normalizer,node_limiter,node_cache,node_config,node_goofish toneIndigo
```

## Components

### Search dashboard

- [Search and results UI](https://github.com/uwavo/goofish-live-search/blob/master/frontend/app.js): `frontend/app.js`

### Search API

- [Web application](https://github.com/uwavo/goofish-live-search/blob/master/backend/main.py): `backend/main.py`
- [Search endpoints](https://github.com/uwavo/goofish-live-search/blob/master/backend/routes.py): `backend/routes.py`

### Listing discovery

- **Bing search**
- [Indexed listing discovery](https://github.com/uwavo/goofish-live-search/blob/master/backend/discovery.py): `backend/discovery.py`

### Browser runtime

- [Browser engine and hydration](https://github.com/uwavo/goofish-live-search/blob/master/backend/browser_engine.py): `backend/browser_engine.py`

### Search support

- [Query translation](https://github.com/uwavo/goofish-live-search/blob/master/backend/translator.py): `backend/translator.py`
- [Listing normalization and filters](https://github.com/uwavo/goofish-live-search/blob/master/backend/normalizer.py): `backend/normalizer.py`
- [Adaptive rate limiter](https://github.com/uwavo/goofish-live-search/blob/master/backend/rate_limiter.py): `backend/rate_limiter.py`
- [SQLite result cache](https://github.com/uwavo/goofish-live-search/blob/master/backend/cache.py): `backend/cache.py`
- [Runtime configuration](https://github.com/uwavo/goofish-live-search/blob/master/backend/config.py): `backend/config.py`

### Other components

- **Dashboard user**
- **Goofish listings**

## Connections

- Dashboard user → Search and results UI: searches listings (evidence: `README.md`)
- Search and results UI → Search endpoints: requests search (evidence: `frontend/app.js`)
- Web application → Search endpoints: mounts API (evidence: `backend/main.py`)
- Web application → Browser engine and hydration: starts and closes (evidence: `backend/main.py`)
- Search endpoints → Query translation: translates query (evidence: `backend/routes.py`)
- Search endpoints → SQLite result cache: reads and writes (evidence: `backend/routes.py`)
- Search endpoints → Listing normalization and filters: filters prices (evidence: `backend/routes.py`)
- Search endpoints → Browser engine and hydration: gets context (evidence: `backend/routes.py`)
- Search endpoints → Indexed listing discovery: discovers listings (evidence: `backend/routes.py`)
- Indexed listing discovery → Bing search: searches indexes (evidence: `README.md`)
- Indexed listing discovery → Goofish listings: resolves listing pages (evidence: `backend/discovery.py`)
- Browser engine and hydration → Goofish listings: visits item pages (evidence: `README.md`)
- Browser engine and hydration → Listing normalization and filters: normalizes details (evidence: `backend/browser_engine.py`)
- Browser engine and hydration → Adaptive rate limiter: throttles hydration (evidence: `backend/browser_engine.py`)
- Browser engine and hydration → Runtime configuration: uses settings (evidence: `backend/browser_engine.py`)
- SQLite result cache → Runtime configuration: uses cache settings (evidence: `backend/cache.py`)
- Adaptive rate limiter → Runtime configuration: uses rate setting (evidence: `backend/rate_limiter.py`)
- Query translation → Bing search: supports Chinese queries
- Search endpoints → Search and results UI: returns listings (evidence: `frontend/app.js`)
