ctr-engine

Fresh

Source: BIBLE.md (Phase 3 Fill critical stubs, Phase 4 CTR realism, Phase 10 Route wrappers)

The core CTR plugin. Searches Google from a specific city, finds the target domain, clicks it with real mouse coordinates, dwells with internal link traversal.

What it does

flowchart TD
  S[Start] --> PA[Pick account from store]
  PA --> LB[Launch browser with fingerprint + proxy]
  LB --> WS[1-3 warmup searches]
  WS --> MS[Money keyword search with UULE]
  MS --> PC[Pre-click: 0/1/2 non-target organics]
  PC --> FT[Find target domain in SERP]
  FT --> CL[Click with real coords + ±15/±4px jitter]
  CL --> DD[Deep dwell: scroll, internal links]
  DD --> SC[Save cookies, close]
  SC --> M[markAction in account store]

Routes

Method	Route	What
POST	/ctr/run	Single CTR session
POST	/ctr/batch	Batch CTR sessions
GET	/campaigns	List active campaigns

Example payload

curl -X POST http://localhost:4700/ctr/run \
  -H "Content-Type: application/json" \
  -H "x-api-key: ghost-engine-key" \
  -d '{
    "keyword": "junk removal dallas",
    "targetDomain": "journeyjunkremoval.com",
    "city": "Dallas",
    "state": "TX",
    "dwellTime": "medium"
  }'

Parameters

Parameter	Values	Default	Description
keyword	any string	required	Google search query
targetDomain	domain	required	Domain to find and click
city	string	required	City for UULE encoding
state	2-letter code	required	State for geo-targeting
dwellTime	short/medium/long	medium	Time on site
email	account email	random	Specific account
warmupSearches	true/false	true	Warmup queries first
maxPages	1-10	3	SERP pages to search
testMode	true/false	false	Caps dwell at 60s

Dwell time breakdown

Mode	Time on site	Scrolls	Internal clicks
short	60-120 s	3-5	1
medium	180-240 s	5-8	1-3
long	300-600 s	8-12	2-3

Pre-click behavior

Weighted random distribution:

• 40% zero non-target clicks
• 40% one non-target organic click (10-30 s dwell each, then back)
• 20% two non-target organic clicks (10-30 s each)

Then click target, back-navigate, click target again to look like a "this is the result" choice.

Warmup searches

1 to 3 semantically related but non-commercial searches before the money keyword.

Examples:

• "dallas weather" before "junk removal dallas"
• "best pizza dallas" before "junk removal dallas"
• "dallas events this weekend" before "junk removal dallas"

City-specific plus industry-related query pools.

SERP click

All clicks use real mouse coordinates via POST /browser/:id/click {x, y}, not JS .click().

• Bounding rect from getBoundingClientRect()
• Slight randomization: ±15 px on x, ±4 px on y
• Humanized mouse path from current cursor to target

Deep dwell

3 to 12 variable scrolls with pauses. 1 to 3 internal link clicks (same domain). 15 to 60 s sub-dwell on each internal page. Back-navigate after each.

Return shape

{
  "success": true,
  "keyword": "junk removal dallas",
  "targetDomain": "journeyjunkremoval.com",
  "location": "Dallas, TX",
  "found": true,
  "position": 7,
  "dwelledMs": 198420,
  "totalTimeMs": 312000,
  "warmupSearches": 2,
  "preClicks": 1,
  "internalClicks": 3
}

How it fits with other plugins

• Uses core/account-store to load account data
• Uses core/uule for geo-targeting
• Uses core/browser-search for SERP parsing (PARSE_ORGANIC_RESULTS script)
• Updates core/result-store after each run
• Coordinates with campaign-manager for account locks
• Triggered by scheduler jobType ctr

Related

• Campaign Manager
• CTR Campaign workflow
• CTR API routes