flowchart TD subgraph UI Layer MainWindow[Main Window] SettingsDialog[Settings Dialog] SeoWindow[SEO Suite Window] PipelinePanel[Pipeline Panel] DiscoveryPanel[Discovery Panel] end subgraph Core Services Config[AppConfig] Paths[Path Resolver] Signals[AppSignals] DataManager[DataManager (SQLite)] Registry[Windows Registry] Launchers[AI Launchers] end subgraph Workers WebCopyWorker[WebCopy Worker] DiscoveryWorker[Discovery Worker] ColdCallWorker[Cold Call Worker] DeployWorker[Deploy Worker] end subgraph SEO Suite Audit[SEO Audit] Keywords[Keyword Analysis] SchemaGen[Schema Generator] ReportGen[Report Generator] end subgraph Documentation DocsSite[Static Docs Site] end MainWindow --> SettingsDialog MainWindow --> SeoWindow MainWindow --> PipelinePanel MainWindow --> DiscoveryPanel SettingsDialog --> Config SettingsDialog --> Paths SettingsDialog --> DataManager SeoWindow --> Audit SeoWindow --> Keywords SeoWindow --> SchemaGen SeoWindow --> ReportGen PipelinePanel --> DataManager DiscoveryPanel --> DiscoveryWorker DiscoveryPanel --> DataManager Workers --> DataManager Workers --> Launchers DataManager --> SQLiteDB[(SQLite Database)] DataManager --> ExportImport[Export / Import (SQLite)] DocsSite --> UI Layer DocsSite --> Core Services DocsSite --> SEO Suite classDef ui fill:#E0F7FA,stroke:#006064,stroke-width:2px; classDef core fill:#FFF3E0,stroke:#BF360C,stroke-width:2px; classDef workers fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px; classDef seo fill:#F3E5F5,stroke:#4A148C,stroke-width:2px; classDef docs fill:#ECEFF1,stroke:#263238,stroke-width:2px; class UI Layer ui; class Core Services core; class Workers workers; class SEO Suite seo; class Documentation docs;

Architecture Overview

How Hippopotamoose All In One is built — from top-level structure to core subsystems.

Technology Stack

Layer	Technology	Why
UI Framework	PyQt6	Native Windows look, robust widget toolkit, QThread for non-blocking I/O
Language	Python 3.11+	Rapid development, excellent library ecosystem
Browser Preview	PyQt6 QWebEngineView	Chromium-based, embedded in the UI
AI Delegation	Claude Code CLI / Gemini CLI	Spawned as child processes; handles long-running autonomous work outside the main process
Site Deployment	Cloudflare Pages + Wrangler CLI	Free tier, global CDN, custom domains, instant deploys
Site Downloads	Cyotek WebCopy	Handles auth, redirects, relative URL rewriting for offline viewing
Stock Photo Detection	Playwright + Chromium	Google Lens requires a real browser; Playwright automates it
Credential Storage	Windows Registry (winreg)	Secure OS-level storage, not exposed in filesystem
State Storage	Flat JSON files	Simple, portable, human-readable
Build/Packaging	PyInstaller + Inno Setup	Produces a self-contained Windows installer with all dependencies bundled

Application Layers

Entry Point

main.py — Detects frozen (packaged) vs. source context, sets APP_DIR, initializes configuration, creates the QApplication with the global dark stylesheet, and shows the MainWindow.

Main Window

main_window.py — A QMainWindow containing a vertical QSplitter. The top half holds a horizontal QSplitter with the Discovery Panel (left) and Swiper Panel (right). The bottom half is the Pipeline Panel. A toolbar at the top contains the Build from Scratch button, Add Existing Site button, and Settings gear.

Core Subsystems (`core/`)

Module	Role
`config.py`	Frozen AppConfig dataclass. All filesystem paths derive from a single `app_root`. Singleton pattern — call `init_config(app_root)` once, then `config()` anywhere.
`signals.py`	AppSignals singleton (QObject). Cross-module signal bus. Emits queue_updated, pipeline_added/updated/removed, data_reset.
`data_manager.py`	Central state store. Owns pipeline, queue, and rejected lists in memory. Atomic write to disk. Crash-safe step recovery on startup.
`registry.py`	Read/write Windows Registry under HKCU\Software\Hippopotamoose\AllInOne. Typed accessors for all keys.
`ai_launcher.py`	Routes to claude_launcher or gemini_launcher based on USE_GEMINI_CLI registry flag.
`claude_launcher.py`	Writes prompt to temp file, spawns PowerShell window with `claude --dangerously-skip-permissions`. Returns (process, ProcessMonitor).
`process_monitor.py`	QThread. Calls proc.wait() and emits finished(exit_code) when the spawned process terminates.
`webcopy_queue.py`	Bounded concurrency pool (max 3 concurrent WebCopy jobs). Two job types: pipeline (enqueue) and example (enqueue_example).
`webcopy_worker.py`	QThread wrapping wcopy.exe. Parses stdout for progress. 5-minute hard timeout.
`deploy_worker.py`	QThread running deploy-demo.ps1 hidden. 3-minute timeout. Returns demo URL on success. Also encrypts any `.md` files in the site folder and publishes them to the shared client-docs project via `_publish_markdown()`.
`cold_call_worker.py`	Silent Claude invocation to extract contact JSON from downloaded HTML files.
`backup_worker.py`	QThread. Copies edited_sites/<slug> → Site Backups/<slug>/Edition N.
`discovery_worker.py`	QThread. Calls Google Places API for each spiral tile.
`report_crypto.py`	AES-256-GCM encryption for client documents. Maintains a local `docs-index.json` with stable UUIDs and keys. Generates fragment URLs in the format `#uuid:base64url-key`. Never deployed — decryption happens in the browser via WebCrypto.
`clear_data.py`	QThread worker that wipes all filesystem state (downloaded sites, edited sites, backups, JSON data files) while leaving API keys in the Windows Registry untouched.

UI Modules (`ui/`)

Module	Role
`pipeline_panel.py`	Scrollable container that holds all PipelineRowWidget instances. Wires up the AppSignals bus to create, update, and remove rows as pipeline data changes.
`pipeline_row_widget.py`	The core UI element. One row per lead. Contains 9 step cells (Demo, C-Chk 1, Host, Cold Call, Form, C-Chk 2, Iterate, Hosting, SEO), action buttons, URL links, and note/folder/remove/delete controls.
`discovery_panel.py`	Niche/coordinates/radius/chunks inputs. Preset management. Queue/Rejected list toggle.
`swiper_panel.py`	QWebEngineView browser. Pass/Example/Copy buttons and keyboard shortcuts. Download progress display.
`settings_dialog.py`	Full settings management: API keys, AI models, export/import, clear data.
`scratch_popup.py`	Build from Scratch dialog. Both path A (existing folder) and path B (AI build).
`cold_call_popup.py`	Scrollable contact list with per-row copy buttons.
`seo_window.py`	Multi-tab SEO suite: Audit (on-page checks), Keywords (density table), AI Enhancement (Claude Opus rewrite), Report & Publish (encrypt + deploy to client-docs), Compare Sites (original vs. rebuilt diff), and Performance (Lighthouse via npx).
`note_popup.py`	Free-text note editor per pipeline entry.
`manual_add_dialog.py`	Dialog to add a site that already exists on disk directly to the pipeline without running AI.
`toast.py`	Non-modal auto-dismiss notification overlays, stacked bottom-right.

SEO Subsystem (`seo/`)

Module	Role
`audit.py`	Core HTML parser. Checks title length, meta description, H1 count, H2 presence, image alt text, and word count per page.
`models.py`	Shared dataclasses: `PageResult`, `Finding`, severity enum.
`technical.py`	Technical SEO checks: canonical tags, robots meta, sitemap presence, HTTPS links, duplicate titles/descriptions.
`local_seo.py`	Local SEO checks: NAP (Name/Address/Phone) consistency, Google Maps embed, LocalBusiness schema detection.
`geo.py`	AI/GEO readiness checks: structured data coverage, FAQ schema, llms.txt presence, content quality signals.
`keywords.py`	Keyword density analysis. Builds per-page tables of top terms, their H1/H2/meta/paragraph presence, count, and density %.
`schema_gen.py`	Generates JSON-LD structured data snippets (LocalBusiness, FAQPage, etc.) for injection into the site.
`llms_txt.py`	Generates an `llms.txt` file in the site root — a plain-text summary for AI crawlers.
`sitemap_gen.py`	Generates `sitemap.xml` from the site's HTML file list.
`report_gen.py`	Compiles all SEO findings into a client-facing `seo-report.md` for publishing via the encrypted docs pipeline.

Signal Flow

The app uses PyQt6 signals to communicate between layers without tight coupling:

Workers emit signals (e.g. finished(bool, url)) on the thread they run in
Qt's signal-slot mechanism automatically marshals these to the main thread for UI updates
The AppSignals singleton provides a global event bus for cross-module events (pipeline changes, queue updates)

Threading Model

The main thread runs the Qt event loop and all UI. Every blocking operation runs in a QThread worker:

WebCopy downloads — WebCopyWorker QThread
Cloudflare deployments — DeployWorker QThread
Cold call scraping — ColdCallWorker QThread
Google Places API calls — DiscoveryWorker QThread
Site backups — BackupWorker QThread
AI CLI process monitoring — ProcessMonitor QThread

AI work itself runs in separate spawned terminal windows, not in the app's process at all — this keeps the UI fully responsive during 10-minute AI builds.

Export & Import Move your data to another machine File & Directory Structure Every file explained