# Web Crawler Integration Contract

The static web UI in this folder is intentionally decoupled from crawler implementation work.

## Placeholder Hooks

- Preferred future HTTP endpoint: `GET /api/stock`
- Query parameters: `product`, `postalCode`, `radius`, `maxPrice`
- Browser bridge fallback: `window.vendorRadarCrawler.getStock(filters)`
- Manual render hook: `window.renderVendorRadarStock(payload)`

## Accepted Payloads

The UI accepts either the existing MCP-style combined payload:

```json
{
  "scraped_at": "2026-06-30T04:00:00+00:00",
  "retailers": {
    "hornbach": {
      "total_stores": 2,
      "in_stock_count": 1,
      "stores": [
        {
          "city": "Berlin",
          "distance_km": 8,
          "price": 799,
          "stock": 4,
          "updated_at": "1 min ago"
        }
      ]
    }
  }
}
```

Or a flat store payload:

```json
{
  "scraped_at": "2026-06-30T04:00:00+00:00",
  "stores": [
    {
      "retailer": "bauhaus",
      "city": "Berlin",
      "distance_km": 8,
      "price": 799,
      "stock": 4,
      "updated_at": "1 min ago"
    }
  ]
}
```

## Notes For Crawler Agents

- Keep crawler modules in `crawlers/`.
- Do not make the static UI import crawler Python code.
- If adding an HTTP adapter, expose the route beside the MCP server or through a separate small app.
- Preserve the MCP tools in `server.py`: `get_stock`, `get_all_stock`, `get_in_stock_only`, and `debug_retailer`.