# ddcat-main/cursor-auto-register architecture

> Architecture diagram of the GitHub repository ddcat-main/cursor-auto-register, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ddcat-main/cursor-auto-register
- Repository: https://github.com/ddcat-main/cursor-auto-register

## Overview

##### Project Type and Purpose
- This is an automation tool built primarily in Python. Its core function is to automate the registration process for Cursor accounts.
- The project serves as a backend API (with a built-in UI) for account registration. It interacts with headless Chrome (for browser-based automation), manages email verification, and uses a SQLite database for persistence.
- It also contains modules that extend or patch functionalities (e.g., “cursor_shadow_patcher”, “turnstilePatch”), and it relies on external email services and DNS/cloudflare configurations.

##### File Structure Insights and Architectural Components
a. API Server & User Interface:
- api.py: Serves as the main entry point for API endpoints (e.g., GET /accounts, GET /account/random, POST /account). Likely based on a modern Python web framework.
- index.html, static/css, static/js, and images: Provide a web UI that allows users to interact with the API (shown by the screenshots and provided UI endpoints in the README).

b. Core Business Logic Modules:
- cursor_auth_manager.py, cursor_pro_keep_alive.py, and cursor_shadow_patcher.py: These files suggest components that handle authentication flows, session keep-alive mechanisms, and possibly dynamic behavior modifications or patches related to Cursor.
- browser_utils.py: Contains utilities for browser automation (possibly managing headless Chrome interactions).
- get_email_code.py: Likely implements the logic to retrieve email codes for verification.
- reset_machine.py and restart.sh: Scripts for resetting or restarting services, emphasizing that managing the lifecycle of automated processes is part of the system’s concern.

c. Configuration and Logging:
- config.py: Responsible for reading and processing configuration values (from a .env file as detailed in the README).
- logger.py: Implements logging to track system behavior, errors, or activities (as per the suggestion to check logs with “tail -f app.log”).

d. Persistence & Database:
- database.py: Handles database operations. According to the README, account data is persisted in a SQLite database (accounts.db).
- migrate_add_id.py: Indicates that there are database migrations involved – an important architectural element for managing data evolution.

e. Tokens and External Interfaces:
- The tokenManager directory: Contains modules like cursor.py, oneapi_cursor_cleaner.py, and oneapi_manager.py, which handle token management and possibly work with external APIs or cleanup routines.
- turnstilePatch folder: Likely contains patches or scripts to bypass or integrate with external services (e.g., handling turnstile challenges).

f. Deployment and Environment Configuration:
- Files like .env.example, vercel.json, and requirements.txt indicate configuration for environment variables, dependency management, and potentially deployment settings (Vercel for serverless deployments).

a. Main Components and Their Interactions:
- API Gateway/Server (api.py):
- Depicts the entry point for client HTTP requests.
- Should list endpoints like /accounts, /account/random, /account (creation).
- Connects with business logic and database components.
- Business Logic Layer:
- Components for browser automation (browser_utils.py), cursor management (cursor_auth_manager.py, cursor_pro_keep_alive.py, cursor_shadow_patcher.py), and email code retrieval (get_email_code.py).
- Modules in the tokenManager and turnstilePatch directories as side components that augment or handle specific tasks.
- Persistence Layer:
- Use a module for database management (database.py) with a note that accounts are stored in a SQLite (accounts.db) file.
- Migration scripts like migrate_add_id.py should be indicated as part of maintaining/updating the data schema.
- Configuration & Utilities:
- A configuration module (config.py) that processes environment variables.
- A logging component (logger.py) to track application logs.
- Frontend/UI:
- Static assets (index.html, static folder) that provide the user interface.
- That the UI is served via the API and integrates with tools such as Swagger (as noted in the documentation).
- External Integrations:
- Email service interactions (via get_email_code.py and the environmental email settings).

b. Relationships and Data Flow:
- API layer to the business logic modules showing how incoming requests trigger the registration workflow, which then interacts with the browser automation utilities.
- Link the business logic back to the persistence layer for storing/retrieving account information.
- Interactions with external services such as the temporary email service (via GET/POST requests) and possibly the headless browser.
- That deployment/configuration modules (e.g., config.py) feed settings into all major components.

c. Architectural Patterns and Technologies:
- Though not explicitly stated, the project follows a service-oriented (or micro-module) design where responsibilities are divided: (i) API handling, (ii) business logic for Cursor automation, (iii) utility modules for configuration and logging, and (iv) database management.
- Separation between the presentation layer (static HTML/JS UI) and the backend.
- That dependency injection or central configuration management are implied by the emphasis on .env file configurations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    Client["Client (Browser/API Consumer)"]:::external

    %% API & UI Layer
    subgraph "API & UI Layer"
        APIServer["API Server (api.py)"]:::api
        UI["UI Frontend (index.html & static/)"]:::ui
    end

    Client -->|"sends_request"| APIServer
    APIServer -->|"serves_UI"| UI

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        CursorAuth["Cursor Auth Manager (cursor_auth_manager.py)"]:::business
        CursorKeepAlive["Cursor Keep Alive (cursor_pro_keep_alive.py)"]:::business
        CursorShadowPatcher["Cursor Shadow Patcher (cursor_shadow_patcher.py)"]:::business
        BrowserAutomation["Browser Automation (browser_utils.py)"]:::business
        EmailVerification["Email Verification (get_email_code.py)"]:::business
    end

    %% Connections from API Server to Business Logic
    APIServer -->|"handles_registration"| CursorAuth
    APIServer -->|"manages_session"| CursorKeepAlive
    APIServer -->|"applies_patch"| CursorShadowPatcher
    APIServer -->|"initiates_browser_automation"| BrowserAutomation
    APIServer -->|"verifies_email"| EmailVerification

    %% Persistence Layer
    subgraph "Persistence Layer"
        Database["Database Handler (database.py)"]:::database
        Migration["Migration Script (migrate_add_id.py)"]:::database
    end

    BrowserAutomation -->|"stores_account"| Database
    CursorAuth -->|"saves_credentials"| Database
    CursorKeepAlive -->|"updates_session"| Database

    %% Token Management Layer
    subgraph "Token Management Layer"
        CursorToken["Cursor Token (tokenManager/cursor.py)"]:::token
        OneapiCleaner["OneAPI Cursor Cleaner (tokenManager/oneapi_cursor_cleaner.py)"]:::token
        OneapiManager["OneAPI Manager (tokenManager/oneapi_manager.py)"]:::token
    end

    EmailVerification -->|"invokes_token"| CursorToken
    EmailVerification -->|"invokes_token"| OneapiCleaner
    EmailVerification -->|"invokes_token"| OneapiManager

    %% Utility & Configuration
    subgraph "Utility & Configuration"
        Configuration["Configuration (config.py, .env.example)"]:::config
        Logger["Logging Utility (logger.py)"]:::util
        ProcessReset["Reset Script (reset_machine.py)"]:::util
        ProcessRestart["Restart Script (restart.sh)"]:::util
    end

    APIServer -->|"loads_config"| Configuration
    APIServer -->|"logs_events"| Logger
    APIServer -->|"controls_process"| ProcessReset
    APIServer -->|"controls_process"| ProcessRestart

    %% External Integration - Turnstile Patch
    subgraph "Turnstile Patch"
        TPManifest["Manifest (turnstilePatch/manifest.json)"]:::external
        TPReadme["Readme (turnstilePatch/readme.txt)"]:::external
        TPScript["Script (turnstilePatch/script.js)"]:::external
    end

    CursorShadowPatcher -->|"integrates_with"| TPManifest

    %% Deployment & Dependencies
    subgraph "Deployment & Dependencies"
        Deployment["Deployment Config (vercel.json)"]:::config
        Dependencies["Dependencies (requirements.txt)"]:::config
    end

    Configuration -->|"defines_deployment"| Deployment
    Configuration -->|"defines_dependencies"| Dependencies

    %% Class Styles
    classDef api fill:#F4A261,stroke:#333,stroke-width:2px;
    classDef ui fill:#E9C46A,stroke:#333,stroke-width:2px;
    classDef business fill:#2A9D8F,stroke:#333,stroke-width:2px;
    classDef database fill:#264653,stroke:#fff,stroke-width:2px;
    classDef config fill:#E76F51,stroke:#333,stroke-width:2px;
    classDef util fill:#6A994E,stroke:#333,stroke-width:2px;
    classDef external fill:#457B9D,stroke:#333,stroke-width:2px;
    classDef token fill:#A8DADC,stroke:#333,stroke-width:2px;

    %% Click Events
    click APIServer "https://github.com/ddcat-main/cursor-auto-register/blob/main/api.py"
    click UI "https://github.com/ddcat-main/cursor-auto-register/blob/main/index.html"
    click BrowserAutomation "https://github.com/ddcat-main/cursor-auto-register/blob/main/browser_utils.py"
    click CursorAuth "https://github.com/ddcat-main/cursor-auto-register/blob/main/cursor_auth_manager.py"
    click CursorKeepAlive "https://github.com/ddcat-main/cursor-auto-register/blob/main/cursor_pro_keep_alive.py"
    click CursorShadowPatcher "https://github.com/ddcat-main/cursor-auto-register/blob/main/cursor_shadow_patcher.py"
    click EmailVerification "https://github.com/ddcat-main/cursor-auto-register/blob/main/get_email_code.py"
    click Database "https://github.com/ddcat-main/cursor-auto-register/blob/main/database.py"
    click Migration "https://github.com/ddcat-main/cursor-auto-register/blob/main/migrate_add_id.py"
    click Configuration "https://github.com/ddcat-main/cursor-auto-register/blob/main/config.py"
    click Logger "https://github.com/ddcat-main/cursor-auto-register/blob/main/logger.py"
    click ProcessReset "https://github.com/ddcat-main/cursor-auto-register/blob/main/reset_machine.py"
    click ProcessRestart "https://github.com/ddcat-main/cursor-auto-register/blob/main/restart.sh"
    click CursorToken "https://github.com/ddcat-main/cursor-auto-register/blob/main/tokenManager/cursor.py"
    click OneapiCleaner "https://github.com/ddcat-main/cursor-auto-register/blob/main/tokenManager/oneapi_cursor_cleaner.py"
    click OneapiManager "https://github.com/ddcat-main/cursor-auto-register/blob/main/tokenManager/oneapi_manager.py"
    click TPManifest "https://github.com/ddcat-main/cursor-auto-register/blob/main/turnstilePatch/manifest.json"
    click TPReadme "https://github.com/ddcat-main/cursor-auto-register/blob/main/turnstilePatch/readme.txt"
    click TPScript "https://github.com/ddcat-main/cursor-auto-register/blob/main/turnstilePatch/script.js"
    click Deployment "https://github.com/ddcat-main/cursor-auto-register/blob/main/vercel.json"
    click Dependencies "https://github.com/ddcat-main/cursor-auto-register/blob/main/requirements.txt"
```
