# zhangkai208/grok-register-panel architecture

> Architecture diagram of the GitHub repository zhangkai208/grok-register-panel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhangkai208/grok-register-panel
- Repository: https://github.com/zhangkai208/grok-register-panel

## Overview

#### Purpose and entry points
This is a Python-based Grok/xAI account registration automation system with a local authenticated control panel. The main operator entry point is `webui/monitor.py`, serving a localhost panel on port 8787. Registration can also run from CLI batch entry points: `run_batch_headless.py`, `run_until_100.py`, and `batch_supervisor.py`.

#### Control panel and orchestration
The panel manages registration jobs, worker processes, runtime status, provider configuration, proxy configuration, blacklists, and recovery operations. `webui/monitor.py` is the HTTP/UI boundary; it delegates process lifecycle work to `webui/process_utils.py` and registration control to `batch_supervisor.py`. Authentication and local-runtime security are handled by `webui/security_utils.py`.

#### Registration workflow
`register_flow.py` is the core registration state machine: it coordinates browser-driven signup, email verification, and credential output. Browser abstraction is split between `browser_session.py` and `camoufox_adapter.py`, allowing the flow to drive the Camoufox browser runtime rather than directly coupling all registration logic to browser APIs. `cloudflare.py` and `connectivity.py` support network/challenge and reachability concerns around this flow.

#### Batch execution boundary
`batch_supervisor.py` manages concurrent or repeated registration workers and isolates job execution from the web process. `run_batch_headless.py` is the primary headless worker launcher, while `run_xvfb_smoke.py` supports Linux/Xvfb browser execution validation. This separation enables the panel to supervise subprocesses rather than executing browser automation inside its HTTP request lifecycle.

#### Email-provider subsystem
Email acquisition and verification-code retrieval are provider-pluggable through `email_providers/__init__.py` and `email_providers/common.py`. Concrete backends include Cloudflare, DuckMail, Mailnest, MoEmail, and others under `email_providers/`. The Cloudflare provider (`email_providers/cloudflare.py`) connects to a separately deployed Cloudflare Worker API backed by Cloudflare Email Routing and D1, so that infrastructure is external to this repository.

#### Persistent operational state
The panel persists editable operational settings through store modules: `webui/email_provider_store.py`, `webui/email_domain_store.py`, `webui/proxy_store.py`, and `webui/blacklist_store.py`. These form the boundary between panel-managed configuration/state and worker consumption. Runtime outputs and sensitive artifacts are organized in `accounts/`, `grok2api_auth/`, `cpa_auth/`, and `log/`; `secure_files.py` protects sensitive file handling.

#### Authentication artifact conversion and recovery
After successful account/session acquisition, `sso_to_auth_json.py` converts SSO/session material into auth JSON artifacts. Recovery paths are exposed through `webui/recovery_ops.py`, with related registration/SSO logic in `register_flow.py`. These artifacts are intended for downstream API use rather than being only browser-session state.

#### Runtime and deployment
The project runs on Python with dependencies in `requirements.txt` and requires Camoufox browser assets. It supports native Windows and Linux; Linux-specific service deployment is represented by `deploy/grok-register-panel.service.example`. Production hardening and permission controls are documented/implemented through `HARDENING_ROOTS.md`, `scripts/harden_runtime_permissions.py`, and `DEPLOYMENT.md`. External dependencies include xAI/Grok web endpoints, proxy services, email-provider APIs, and optionally Cloudflare Workers, Email Routing, and D1.

Main entry points: [`webui/monitor.py`](https://github.com/zhangkai208/grok-register-panel/blob/main/webui/monitor.py) (Local monitor panel), [`register_flow.py`](https://github.com/zhangkai208/grok-register-panel/blob/main/register_flow.py) (Registration flow), [`batch_supervisor.py`](https://github.com/zhangkai208/grok-register-panel/blob/main/batch_supervisor.py) (Batch supervisor), [`email_providers/__init__.py`](https://github.com/zhangkai208/grok-register-panel/blob/main/email_providers/__init__.py) (Provider interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Local control panel"]
  node_panel["Local monitor panel<br/>HTTP/UI boundary<br/>[monitor.py]"]
  node_security["Local security<br/>auth utilities<br/>[security_utils.py]"]
  node_process_utils["Process lifecycle<br/>process utilities<br/>[process_utils.py]"]
  node_recovery["Recovery operations<br/>recovery API<br/>[recovery_ops.py]"]
end

subgraph group_execution["Registration execution"]
  node_supervisor{{"Batch supervisor<br/>job orchestrator"}}
  node_headless["Headless worker launcher<br/>worker entry point"]
  node_register_flow{{"Registration flow<br/>signup state machine<br/>[register_flow.py]"}}
  node_browser_session["Browser session<br/>browser abstraction<br/>[browser_session.py]"]
  node_camoufox_adapter["Camoufox adapter<br/>browser runtime adapter"]
  node_network_support["Network and challenge support<br/>connectivity layer<br/>[cloudflare.py]"]
end

subgraph group_email["Email providers"]
  node_provider_interface{{"Provider interface<br/>email provider registry<br/>[__init__.py]"}}
  node_provider_common["Provider common logic<br/>provider contract<br/>[common.py]"]
  node_cf_provider["Cloudflare email provider<br/>provider backend<br/>[cloudflare.py]"]
end

subgraph group_state["Operational state and artifacts"]
  node_email_provider_store[("Email provider settings<br/>settings store")]
  node_email_domain_store[("Email domain settings<br/>settings store")]
  node_proxy_store[("Proxy settings<br/>settings store<br/>[proxy_store.py]")]
  node_blacklist_store[("Blacklist state<br/>state store<br/>[blacklist_store.py]")]
  node_auth_converter["SSO auth converter<br/>artifact converter"]
  node_runtime_artifacts["Account and auth artifacts<br/>sensitive runtime files"]
  node_secure_files["Sensitive file protection<br/>file security<br/>[secure_files.py]"]
end

node_xai(("xAI/Grok endpoints<br/>external service"))
node_cf_email_api(("Cloudflare Worker email API<br/>external infrastructure"))

node_panel -->|"authenticates operator"| node_security
node_panel -->|"manages processes"| node_process_utils
node_panel -->|"controls jobs"| node_supervisor
node_panel -->|"exposes recovery"| node_recovery
node_panel -->|"edits"| node_email_provider_store
node_panel -->|"edits"| node_email_domain_store
node_panel -->|"edits"| node_proxy_store
node_panel -->|"edits"| node_blacklist_store
node_process_utils -->|"starts and stops"| node_supervisor
node_supervisor -->|"launches workers"| node_headless
node_headless -->|"runs"| node_register_flow
node_email_provider_store -->|"worker configuration"| node_supervisor
node_email_domain_store -->|"worker configuration"| node_supervisor
node_proxy_store -->|"worker configuration"| node_supervisor
node_blacklist_store -->|"worker constraints"| node_supervisor
node_recovery -->|"reuses registration and SSO logic"| node_register_flow
node_register_flow -->|"drives signup"| node_browser_session
node_browser_session -->|"uses"| node_camoufox_adapter
node_camoufox_adapter -->|"automates"| node_xai
node_register_flow -->|"uses"| node_network_support
node_network_support -->|"supports reachability and challenges"| node_xai
node_register_flow -->|"acquires email and codes"| node_provider_interface
node_provider_interface -->|"uses contract"| node_provider_common
node_provider_interface -->|"selects backend"| node_cf_provider
node_cf_provider -->|"calls"| node_cf_email_api
node_register_flow -->|"passes session material"| node_auth_converter
node_auth_converter -->|"writes auth output"| node_runtime_artifacts
node_register_flow -->|"writes account output"| node_runtime_artifacts
node_secure_files -->|"protects"| node_runtime_artifacts

click node_panel "https://github.com/zhangkai208/grok-register-panel/blob/main/webui/monitor.py"
click node_security "https://github.com/zhangkai208/grok-register-panel/blob/main/webui/security_utils.py"
click node_process_utils "https://github.com/zhangkai208/grok-register-panel/blob/main/webui/process_utils.py"
click node_recovery "https://github.com/zhangkai208/grok-register-panel/blob/main/webui/recovery_ops.py"
click node_supervisor "https://github.com/zhangkai208/grok-register-panel/blob/main/batch_supervisor.py"
click node_headless "https://github.com/zhangkai208/grok-register-panel/blob/main/run_batch_headless.py"
click node_register_flow "https://github.com/zhangkai208/grok-register-panel/blob/main/register_flow.py"
click node_browser_session "https://github.com/zhangkai208/grok-register-panel/blob/main/browser_session.py"
click node_camoufox_adapter "https://github.com/zhangkai208/grok-register-panel/blob/main/camoufox_adapter.py"
click node_network_support "https://github.com/zhangkai208/grok-register-panel/blob/main/cloudflare.py"
click node_provider_interface "https://github.com/zhangkai208/grok-register-panel/blob/main/email_providers/__init__.py"
click node_provider_common "https://github.com/zhangkai208/grok-register-panel/blob/main/email_providers/common.py"
click node_cf_provider "https://github.com/zhangkai208/grok-register-panel/blob/main/email_providers/cloudflare.py"
click node_email_provider_store "https://github.com/zhangkai208/grok-register-panel/blob/main/webui/email_provider_store.py"
click node_email_domain_store "https://github.com/zhangkai208/grok-register-panel/blob/main/webui/email_domain_store.py"
click node_proxy_store "https://github.com/zhangkai208/grok-register-panel/blob/main/webui/proxy_store.py"
click node_blacklist_store "https://github.com/zhangkai208/grok-register-panel/blob/main/webui/blacklist_store.py"
click node_auth_converter "https://github.com/zhangkai208/grok-register-panel/blob/main/sso_to_auth_json.py"
click node_secure_files "https://github.com/zhangkai208/grok-register-panel/blob/main/secure_files.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_panel,node_security,node_process_utils,node_recovery toneBlue
class node_supervisor,node_headless,node_register_flow,node_browser_session,node_camoufox_adapter,node_network_support toneAmber
class node_provider_interface,node_provider_common,node_cf_provider toneMint
class node_email_provider_store,node_email_domain_store,node_proxy_store,node_blacklist_store,node_auth_converter,node_runtime_artifacts,node_secure_files toneRose
class node_xai,node_cf_email_api toneNeutral
```

## Components

### Local control panel

- [Local monitor panel](https://github.com/zhangkai208/grok-register-panel/blob/main/webui/monitor.py): HTTP/UI boundary · Authenticated localhost operator panel on port 8787. · `webui/monitor.py`
- [Local security](https://github.com/zhangkai208/grok-register-panel/blob/main/webui/security_utils.py): auth utilities · `webui/security_utils.py`
- [Process lifecycle](https://github.com/zhangkai208/grok-register-panel/blob/main/webui/process_utils.py): process utilities · `webui/process_utils.py`
- [Recovery operations](https://github.com/zhangkai208/grok-register-panel/blob/main/webui/recovery_ops.py): recovery API · `webui/recovery_ops.py`

### Registration execution

- [Batch supervisor](https://github.com/zhangkai208/grok-register-panel/blob/main/batch_supervisor.py): job orchestrator · Isolates concurrent registration jobs from the web process. · `batch_supervisor.py`
- [Headless worker launcher](https://github.com/zhangkai208/grok-register-panel/blob/main/run_batch_headless.py): worker entry point · `run_batch_headless.py`
- [Registration flow](https://github.com/zhangkai208/grok-register-panel/blob/main/register_flow.py): signup state machine · Coordinates browser signup, email verification, and credential output. · `register_flow.py`
- [Browser session](https://github.com/zhangkai208/grok-register-panel/blob/main/browser_session.py): browser abstraction · `browser_session.py`
- [Camoufox adapter](https://github.com/zhangkai208/grok-register-panel/blob/main/camoufox_adapter.py): browser runtime adapter · `camoufox_adapter.py`
- [Network and challenge support](https://github.com/zhangkai208/grok-register-panel/blob/main/cloudflare.py): connectivity layer · `cloudflare.py`

### Email providers

- [Provider interface](https://github.com/zhangkai208/grok-register-panel/blob/main/email_providers/__init__.py): email provider registry · Pluggable email acquisition and verification-code retrieval. · `email_providers/__init__.py`
- [Provider common logic](https://github.com/zhangkai208/grok-register-panel/blob/main/email_providers/common.py): provider contract · `email_providers/common.py`
- [Cloudflare email provider](https://github.com/zhangkai208/grok-register-panel/blob/main/email_providers/cloudflare.py): provider backend · `email_providers/cloudflare.py`

### Operational state and artifacts

- [Email provider settings](https://github.com/zhangkai208/grok-register-panel/blob/main/webui/email_provider_store.py): settings store · `webui/email_provider_store.py`
- [Email domain settings](https://github.com/zhangkai208/grok-register-panel/blob/main/webui/email_domain_store.py): settings store · `webui/email_domain_store.py`
- [Proxy settings](https://github.com/zhangkai208/grok-register-panel/blob/main/webui/proxy_store.py): settings store · `webui/proxy_store.py`
- [Blacklist state](https://github.com/zhangkai208/grok-register-panel/blob/main/webui/blacklist_store.py): state store · `webui/blacklist_store.py`
- [SSO auth converter](https://github.com/zhangkai208/grok-register-panel/blob/main/sso_to_auth_json.py): artifact converter · Converts acquired SSO/session material to auth JSON. · `sso_to_auth_json.py`
- **Account and auth artifacts**: sensitive runtime files · Stores account outputs and downstream auth material.
- [Sensitive file protection](https://github.com/zhangkai208/grok-register-panel/blob/main/secure_files.py): file security · `secure_files.py`

### Other components

- **xAI/Grok endpoints**: external service
- **Cloudflare Worker email API**: external infrastructure · Backed by Email Routing and D1 outside this repository.

## Connections

- Local monitor panel → Local security: authenticates operator
- Local monitor panel → Process lifecycle: manages processes
- Local monitor panel → Batch supervisor: controls jobs
- Local monitor panel → Recovery operations: exposes recovery
- Local monitor panel → Email provider settings: edits
- Local monitor panel → Email domain settings: edits
- Local monitor panel → Proxy settings: edits
- Local monitor panel → Blacklist state: edits
- Process lifecycle → Batch supervisor: starts and stops
- Batch supervisor → Headless worker launcher: launches workers
- Headless worker launcher → Registration flow: runs
- Email provider settings → Batch supervisor: worker configuration
- Email domain settings → Batch supervisor: worker configuration
- Proxy settings → Batch supervisor: worker configuration
- Blacklist state → Batch supervisor: worker constraints
- Recovery operations → Registration flow: reuses registration and SSO logic
- Registration flow → Browser session: drives signup
- Browser session → Camoufox adapter: uses
- Camoufox adapter → xAI/Grok endpoints: automates
- Registration flow → Network and challenge support: uses
- Network and challenge support → xAI/Grok endpoints: supports reachability and challenges
- Registration flow → Provider interface: acquires email and codes
- Provider interface → Provider common logic: uses contract
- Provider interface → Cloudflare email provider: selects backend
- Cloudflare email provider → Cloudflare Worker email API: calls
- Registration flow → SSO auth converter: passes session material
- SSO auth converter → Account and auth artifacts: writes auth output
- Registration flow → Account and auth artifacts: writes account output
- Sensitive file protection → Account and auth artifacts: protects