# filippodesilva/cursor-ai-bypass architecture

> Architecture diagram of the GitHub repository filippodesilva/cursor-ai-bypass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filippodesilva/cursor-ai-bypass
- Repository: https://github.com/filippodesilva/cursor-ai-bypass

## Overview

1. **Repository purpose**
   - This is a Python automation toolkit centered on modifying local Cursor-related state, resetting machine/telemetry identifiers, and optionally driving browser-based account registration flows. The code is organized as a small CLI wrapper over a few task-specific modules.

2. **Top-level orchestration**
   - `main.py` is the entry point and likely the command dispatcher. It reads CLI flags such as `--all` and a config path, then coordinates which subsystems run in sequence.
   - The architecture is “orchestrator + workers”: `main.py` controls execution order, while the other modules perform the actual filesystem, browser, or network work.

3. **Configuration boundary**
   - `config.yaml` and `config.json` are the main configuration inputs.
   - These files appear to hold environment-specific values such as local paths, platform choices, and automation settings. The README emphasizes that the tool is meant to adapt to different OS setups, so configuration is a key boundary between reusable logic and machine-specific state.

4. **Local state / telemetry subsystem**
   - `machine_reset.py` and `version_bypass.py` are the local-modification modules.
   - Their role is to touch files or identifiers stored on the user machine, such as telemetry data, machine IDs, version metadata, or Cursor/Windsurf state files like `storage.json`.
   - This subsystem sits entirely on the local filesystem boundary and is distinct from browser automation or external network calls.

5. **Account registration automation**
   - `cursor_registration.py` and `email_automation.py` form the external automation path.
   - `cursor_registration.py` likely drives a headless or semi-headless browser flow through Selenium to create or register an account.
   - `email_automation.py` handles the temporary email provider interaction, probably via HTTP requests, to retrieve verification email content and codes.

6. **Browser automation runtime**
   - `chromedriver.exe` is bundled with the repo, indicating the Selenium workflow depends on a specific ChromeDriver binary rather than requiring the user to install one separately.
   - This makes browser automation an explicit runtime dependency and a separate operational boundary from the Python code itself.

7. **External service boundary**
   - The temp mail service referenced in the README is the primary external service dependency.
   - The automation flow likely alternates between the local browser session and the temp-mail API/site to complete registration and validation steps. That makes the system hybrid: local file manipulation plus remote web interaction.

8. **Data flow across modules**
   - A typical run starts in `main.py`, loads config, and then invokes one or more tasks.
   - For local resets, the flow is: config → filesystem paths → backup/modify local Cursor state.
   - For registration, the flow is: config → temp mail service → browser automation via Selenium → verification email retrieval → account completion.

9. **Cross-platform concerns**
   - The README claims Windows, macOS, and Linux support, so path handling and machine-specific locations are part of the design.
   - The repository includes `chromedriver.exe`, which is Windows-specific, but the overall logic appears intended to branch by OS and use different paths per platform.

10. **Safety and change-management boundary**
   - The README mentions safe backups before modification, so the tool likely treats the original local files as mutable but recoverable assets.
   - This suggests a simple “read/backup/modify” pattern for local state changes, reducing the risk of permanent corruption when the automation touches application data.

11. **Packaging and dependencies**
   - `requirements.txt` and the README point to a Python-based runtime with `selenium`, `requests`, and `pyyaml` as the main libraries.
   - There are no signs of a web frontend, database, or service mesh; this is a single-purpose command-line automation utility with a few clearly separated helper modules.

12. **High-level architecture diagram takeaway**
   - The cleanest diagram would show:
     - a CLI entrypoint (`main.py`)
     - configuration files (`config.yaml` / `config.json`)
     - local filesystem mutation modules (`machine_reset.py`, `version_bypass.py`)
     - browser automation (`cursor_registration.py` + bundled ChromeDriver)
     - external temp-mail network interaction (`email_automation.py`)
     - the Cursor/Windsurf local app state and remote email service as the two primary external boundaries.

Main entry points: [`cursor_registration.py`](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/cursor_registration.py) (Register cursor), [`main.py`](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/main.py) (main.py), [`email_automation.py`](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/email_automation.py) (Temp mail), [`machine_reset.py`](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/machine_reset.py) (Reset state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_main["main.py<br/>CLI orchestrator<br/>[main.py]"]
  node_config["Config"]
end

subgraph group_local["Local state"]
  node_machine_reset["Reset state<br/>filesystem worker<br/>[machine_reset.py]"]
  node_version_bypass["Bypass version<br/>state patcher<br/>[version_bypass.py]"]
  node_cursor_state[("Cursor state<br/>local app data")]
end

subgraph group_browser["Browser automation"]
  node_cursor_registration["Register cursor<br/>browser worker"]
  node_chromedriver["ChromeDriver<br/>selenium runtime<br/>[chromedriver.exe]"]
  node_browser_session(("Browser session<br/>selenium session"))
end

subgraph group_external["External services"]
  node_email_automation["Temp mail<br/>mail automation"]
  node_temp_mail(("Mail service<br/>external service"))
end

node_main -->|"loads"| node_config
node_main -->|"runs"| node_machine_reset
node_main -->|"runs"| node_version_bypass
node_main -->|"runs"| node_cursor_registration
node_machine_reset -->|"modifies"| node_cursor_state
node_version_bypass -->|"patches"| node_cursor_state
node_cursor_registration -->|"uses"| node_chromedriver
node_cursor_registration -->|"drives"| node_browser_session
node_cursor_registration -->|"requests"| node_email_automation
node_email_automation -->|"calls"| node_temp_mail
node_email_automation -.->|"supports"| node_browser_session
node_config -.->|"parametrizes"| node_machine_reset
node_config -.->|"parametrizes"| node_cursor_registration

click node_main "https://github.com/filippodesilva/cursor-ai-bypass/blob/main/main.py"
click node_machine_reset "https://github.com/filippodesilva/cursor-ai-bypass/blob/main/machine_reset.py"
click node_version_bypass "https://github.com/filippodesilva/cursor-ai-bypass/blob/main/version_bypass.py"
click node_cursor_registration "https://github.com/filippodesilva/cursor-ai-bypass/blob/main/cursor_registration.py"
click node_email_automation "https://github.com/filippodesilva/cursor-ai-bypass/blob/main/email_automation.py"
click node_chromedriver "https://github.com/filippodesilva/cursor-ai-bypass/blob/main/chromedriver.exe"

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_main,node_config toneBlue
class node_machine_reset,node_version_bypass,node_cursor_state toneAmber
class node_cursor_registration,node_chromedriver,node_browser_session toneMint
class node_email_automation,node_temp_mail toneRose
```

## Components

### Orchestration

CLI entrypoint and config loading

- [main.py](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/main.py): CLI orchestrator · Command entrypoint that dispatches reset and registration tasks. · `main.py`
- **Config**: runtime config · Environment-specific settings consumed by the CLI and workers.

### Local state

Filesystem-backed Cursor state modifications

- [Reset state](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/machine_reset.py): filesystem worker · Backs up and rewrites local machine and telemetry-related state. · `machine_reset.py`
- [Bypass version](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/version_bypass.py): state patcher · Adjusts local Cursor/Windsurf metadata or version-linked files. · `version_bypass.py`
- **Cursor state**: local app data · Local application storage and machine identifiers targeted by the reset flow.

### Browser automation

Selenium flow and bundled driver

- [Register cursor](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/cursor_registration.py): browser worker · Drives the browser-based account registration or signup flow. · `cursor_registration.py`
- [ChromeDriver](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/chromedriver.exe): selenium runtime · Bundled browser driver used by the Selenium automation. · `chromedriver.exe`
- **Browser session**: selenium session · Live browser context that executes registration steps.

### External services

Remote email and target account flow

- [Temp mail](https://github.com/filippodesilva/cursor-ai-bypass/blob/main/email_automation.py): mail automation · Fetches verification emails and codes from the temporary email service. · `email_automation.py`
- **Mail service**: external service · Remote temporary email provider used for verification.

## Connections

- main.py → Config: loads · Reads configuration before selecting tasks.
- main.py → Reset state: runs · Invokes local reset workflow.
- main.py → Bypass version: runs · Invokes local patching workflow.
- main.py → Register cursor: runs · Starts the account registration flow.
- Reset state → Cursor state: modifies · Backs up and edits local state files.
- Bypass version → Cursor state: patches · Updates version or identity-linked local data.
- Register cursor → ChromeDriver: uses · Depends on the bundled driver binary.
- Register cursor → Browser session: drives · Controls the browser to complete signup steps.
- Register cursor → Temp mail: requests · Delegates email lookup for verification codes.
- Temp mail → Mail service: calls · Interacts with the temporary mail provider.
- Temp mail → Browser session: supports · Feeds verification data back into the browser flow.
- Config → Reset state: parametrizes · Supplies paths and platform-specific settings.
- Config → Register cursor: parametrizes · Supplies automation settings and environment choices.