Architecture

Fresh

Source: BIBLE.md (Architecture section), bible/understand-everything.md

Ghost Engine is a unified desktop plus mobile antidetect browser with three I/O backends.

High-level layout

ghost-engine/
├── server.mjs          # HTTP server, 704 routes
├── cli.mjs             # CLI interface (16 subcommands)
├── dashboard.html      # 13-tab dark theme dashboard
├── core/               # 30 core modules
├── plugins/            # 109+ plugins
├── scripts/            # 290+ automation scripts
├── data/               # 21 dirs, 106 files (persistent state)
└── bible/              # Complete documentation

The three modes

Every browser session runs in one of three modes:

flowchart LR
  A[Launch request] --> R{hybrid-router}
  R -- ghost --> O[OS or ADB + vision]
  R -- hybrid --> H[OS clicks + CDP reads]
  R -- speed --> C[Pure CDP / Puppeteer]
  O --> T1[isTrusted: true]
  H --> T2[isTrusted: true on input]
  C --> T3[isTrusted: false]

Mode	Input source	CDP traces	Use case
Ghost	OS-level (desktop) or ADB (mobile) plus vision	Zero	Reddit, LinkedIn, Facebook, Instagram
Hybrid	OS-level for clicks/typing, CDP for reading	Minimal (reads only)	Yelp, Substack, Gmail
Speed	Pure CDP (same as V1)	Full	YouTube, Google Search

A component called the hybrid router (hybrid-router.mjs) decides which mode to use per platform. Each platform has a default: Reddit defaults to ghost, YouTube defaults to speed. Override per-session.

The three backends

The I/O path:

Backend	Use	isTrusted	Latency
cdp	desktop, speed mode	false	~5 ms/action
os	desktop, ghost/hybrid mode	true	~50 ms/action
adb	mobile, always ghost mode	true	~20 ms/action

ADB always forces ghost mode because there is no CDP on a mobile device. ADB is the only way in.

The four new modules (added on top of V1)

flowchart TB
  HR[hybrid-router.mjs] --> OS[os-input.mjs]
  HR --> ADB[adb-input.mjs]
  HR --> CDP[CDP / Puppeteer]
  OS --> WIN[Windows user32.dll SendInput]
  ADB --> AND[Android Debug Bridge]
  VIS[vision.mjs] --> CL[Claude API]
  VIS --> OL[Ollama]
  VIS --> AI[OpenAI]
  OS --> VIS
  ADB --> VIS

Module	What it does
os-input.mjs	Win32 SendInput/SetCursorPos via PowerShell plus inline C#
adb-input.mjs	ADB touch/keyboard/scroll with Bezier humanization
vision.mjs	Screenshot to VLM to coordinates (page or device)
hybrid-router.mjs	Mode plus backend selection per session

V1 inheritance

Ghost Engine is a clone of V1, not a rewrite. It inherited 13 core modules:

• Bezier mouse curves
• Adjacent-key typo simulation
• Ease-in-out scroll with re-reading
• Markov behavioral walker
• 15-vector fingerprint evasion
• AES-256-GCM cookie encryption
• 251 US metro geo-profiles
• GPS driving simulation
• Cloudflare/DataDome/reCAPTCHA evasion
• Proxy rotation with marriage
• CAPTCHA solving (4 services)
• SERP scraping
• UULE geo-targeting

V1 vs V2

	Mini Engine V1 :4600	Ghost Engine V2 :4700
Use it for	Daily SEO ops, warming, low-risk platforms	Reddit, LinkedIn, mobile, any platform that shadow-bans CDP
Platforms	Desktop only	Desktop (Chrome) + Mobile (Android via ADB)
Input method	CDP Input.dispatchMouseEvent/KeyEvent	Desktop: Windows SendInput. Mobile: ADB touch
Navigation	DOM selectors, CSS queries	Vision or DOM
CDP traces	Present (mitigated by rebrowser)	Zero in ghost mode
Humanization	Bezier mouse, typo keyboard, Markov walker	Same plus OS-level output plus ADB Bezier swipes
Latency	~5 ms per action	Desktop: ~50 ms (PS spawn). Mobile: ~20 ms (ADB shell)
Concurrent sessions	Unlimited	Desktop ghost: one at a time. Mobile: unlimited
VLM cost	None	~$0.003 per vision call (Claude Sonnet)

Service inventory

Port	Service	What it does
4700	Ghost Engine V2	This engine. OS-level input, vision, hybrid routing
4600	Mini Engine V1	Production workhorse. Daily SEO ops. Read-only
3500	Big antidetect engine	Full antidetect, shares stealth strategy
3700	Ponmelli	SEO Command Center. Orchestrates cascades, CTR, ranks
11434	Ollama	Vision and content gen (local)

Invariants

invariants:
  - rule: V1 is untouched
    why: V1 is production. V2 is experimental. Never modify V1 files.

  - rule: Ghost mode = zero CDP Input domain calls
    why: The entire point. If ghost mode still uses CDP for clicks, it is broken.

  - rule: ADB backend always forces ghost mode
    why: No CDP available on mobile. ADB is the only I/O path.

  - rule: Vision is expensive
    why: ~$0.003 per VLM call. Use it only for navigation decisions.

  - rule: Window focus required for OS-level input (desktop only)
    why: SendInput sends events to the foreground window.

  - rule: One desktop ghost session at a time
    why: Only one window can have focus on desktop. ADB targets by serial.

  - rule: Same humanization math across all backends
    why: Desktop Bezier, ADB Bezier, and CDP all use cubic interpolation.

  - rule: Less is more
    why: Every hook is a tell. Adding flags or JS injection lowers scores.