# cloak — module index

## Purpose

HTTP wrapper around CloakBrowser. Scrapes Google / Bing / DDG SERPs and exposes
the parsed organic results as JSON. Used as the third-tier fallback for the AI
platform `web` module when SearXNG + paid rotation return thin results.

## Files

```
cloak/
├── pyproject.toml            FastAPI + uvicorn + cloakbrowser deps
├── README.md                 User-facing docs
├── INDEX.md                  This file (module map)
├── src/cloak/
│   ├── __init__.py
│   ├── config.py             Env-driven pydantic settings (CLOAK_* prefix)
│   ├── schemas.py            Request/Response/Stats pydantic models
│   ├── scraper.py            Per-engine HTML scrapers (google/bing/ddg)
│   ├── browser_pool.py       Bounded async pool of CloakBrowser instances
│   └── server.py             FastAPI app — POST /v1/search, GET /health
├── tests/                    pytest test suite
└── deploy/
    ├── Dockerfile            FROM cloakhq/cloakbrowser:latest + FastAPI
    └── docker-compose.yml    didiAI-cloak on didi-network, port 8770
```

## External contracts

| Surface | Path | Method |
|---|---|---|
| Search | `/v1/search` | POST |
| Health | `/health` | GET |

Both reachable inside the cluster at `http://didiAI-cloak:8770/`. Host-port
`127.0.0.1:8770` is exposed only for local debugging on didi12.

## State

Stateless. No database, no Redis. The browser pool is in-process memory.
Cold-start (warm 3 browsers) ≈ 8–12 s; from then on each search is 2–4 s
end-to-end.

## Dependencies

- `cloakhq/cloakbrowser:latest` Docker base image (bundles stealth Chromium + Xvfb)
- Outbound TCP to `google.com`, `bing.com`, `html.duckduckgo.com`

## Where it's consumed

- `ai_platform/modules/web/src/web/search/cloak.py` (CloakHTTPClient) — implemented
- `ai_platform/modules/web/src/web/orchestrator.py::_run_search_stage` — implemented (tier-3 fallback hook, orchestrator.py:564-599)

Backend services (`agent-v3`, `didi-framework`, admin-dashboard) do NOT call
this service directly.