# wherearemysocks/browsetic architecture

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

- Interactive diagram: https://gitdiagram.com/wherearemysocks/browsetic
- Repository: https://github.com/wherearemysocks/browsetic

## Overview

##### Project Type and Purpose
- Browsetic is clearly a specialized tool designed to control a local web browser (Google Chrome) through user commands. It leverages AI (via the Qwen-VL2.5-72B model) coupled with browser automation (using Playwright) to execute web tasks. The README emphasizes local execution, multi-tab management, and command-based control, indicating a full-stack-like interaction between a UI component on the menu bar and backend automation/orchestration logic.

##### File Structure
- At the root level, there are Python scripts (action.py, agent.py, browser_controller.py, menubar_app.py, vision_llm.py) that appear to encapsulate the main functionalities:
- menubar_app.py – Likely the entry point for the macOS menu bar UI.
- browser_controller.py – Responsible for interfacing with and controlling the browser (via Playwright).
- agent.py and vision_llm.py – Likely handle interaction with the Qwen model and possibly process vision/LLM tasks.
- The prompt directory contains files (agent_prompt.py and prompt_template.txt) that indicate command templates or prompt handling for the AI component.
- The utils directory bundles helper functions like dialog management, error handling, and image conversion. These utilities support the overall architecture.

##### Main Components
a. User Interface Component:
- Menubar Application (menubar_app.py): Entry point presenting the macOS menu bar UI.
b. Command and Prompt Management:
- Prompt Module (prompt/agent_prompt.py and prompt_template.txt): Manages and constructs command prompts.
c. Automation/Orchestration Engine:
- Agent Module (agent.py): Processes user commands and determines the actions to be taken.
- Vision/LLM Integration (vision_llm.py): Interacts with the Qwen model for interpreting commands.
d. Browser Controller:
- Browser Automation (browser_controller.py): Uses Playwright to interact with the local Chrome browser, handling multi-tab management and executing web automation tasks.
e. Utility and Support Modules:
- Utils (utils/*): Provides auxiliary functions like error handling, dialog display, image conversion, and path management which ensure smooth operation.
f. Integration with External Services:
- Qwen API (as described in the README): Although not directly visible in the file tree, the integration with Qwen-VL2.5-72B and API keys from Alibaba Cloud is central to the AI-driven commands.

##### Relationships and Data Flow
- The user issues a command through the macOS menu bar UI.
- The menubar app passes this command to the Agent module, which uses the Prompt module to format or interpret the command.
- The Vision/LLM component (in vision_llm.py) may process the command using the Qwen model.
- Once interpreted, the command is sent to the browser controller, which, utilizing Playwright, interacts with the local Google Chrome.
- Supporting utilities provide error handling, dialog interactions, and image/data conversion at various stages.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is divided into UI, command processing, automation control, and utility functions.
- Modularity: Distinct modules (prompt, agent, browser controller, utils) simplify maintenance and potential scaling.
- Local Execution and State Preservation: The design leverages the already authenticated state of the local browser, reducing the need for redundant authentication.

## Diagram (Mermaid)

```mermaid
graph TD
    User["User"]:::ui

    subgraph "UI Layer"
        menubar["Menubar Application"]
    end

    subgraph "Command Processing Layer"
        agent["Agent Module"]
        subgraph "Prompt Management"
            promptA["Agent Prompt"]
            promptT["Prompt Template"]
        end
        vision["Vision/LLM Module"]
    end

    subgraph "Browser Automation Layer"
        browser["Browser Controller"]
    end

    subgraph "Utility Support"
        utils["Utility Modules"]
    end

    qwen["Qwen API (Qwen-VL2.5-72B)"]:::external

    %% Connections
    User -->|"initiates"| menubar
    menubar -->|"sendsCommand"| agent
    agent -->|"formatsCmd"| promptA
    promptA -->|"usesTemplate"| promptT
    agent -->|"processesCmd"| vision
    agent -->|"triggersAutomation"| browser
    vision -->|"queries"| qwen

    %% Utility support (dotted lines)
    menubar -.->|"supports"| utils
    agent -.->|"supports"| utils
    promptA -.->|"supports"| utils
    promptT -.->|"supports"| utils
    vision -.->|"supports"| utils
    browser -.->|"supports"| utils

    %% Class Definitions
    classDef ui fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef cmd fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef browser fill:#fff9c4,stroke:#f57f17,stroke-width:2px;
    classDef utils fill:#ffe0b2,stroke:#e65100,stroke-width:2px;
    classDef external fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;

    %% Assign classes
    class User,menubar ui;
    class agent,promptA,promptT,vision cmd;
    class browser browser;
    class utils utils;
    class qwen external;

    %% Click Events
    click menubar "https://github.com/wherearemysocks/browsetic/blob/main/menubar_app.py"
    click promptA "https://github.com/wherearemysocks/browsetic/blob/main/prompt/agent_prompt.py"
    click promptT "https://github.com/wherearemysocks/browsetic/blob/main/prompt/prompt_template.txt"
    click agent "https://github.com/wherearemysocks/browsetic/blob/main/agent.py"
    click vision "https://github.com/wherearemysocks/browsetic/blob/main/vision_llm.py"
    click browser "https://github.com/wherearemysocks/browsetic/blob/main/browser_controller.py"
    click utils "https://github.com/wherearemysocks/browsetic/tree/main/utils/"
```
