# bandarlabs/clickclickclick architecture

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

- Interactive diagram: https://gitdiagram.com/bandarlabs/clickclickclick
- Repository: https://github.com/bandarlabs/clickclickclick

## Overview

##### Main Components
- Command-Line Interface & Entry Points:
- Files: main.py, interface.py, and the executable “clickclickclick” package.
- These components handle user-triggered actions (CLI commands, script usage, and API endpoint usage).
- API Layer:
- File: api.py.
- This module exposes an endpoint (using Uvicorn for ASGI) to receive and execute tasks based on provided configurations.
- Configuration Management:
- Directory: clickclickclick/config, containing multiple YAML files (models.yaml, prompts.yaml, function_declarations) and utility code (e.g., yaml_loader.py).
- This part handles model-specific settings and various predefined function declarations for Android, OSX, etc.
- Task Execution Components:
- Executor Module (clickclickclick/executor): Contains platform-specific modules (android.py, osx.py) that handle the actual execution of tasks.
- Task Planning & Model Interaction:
- Planner Module (clickclickclick/planner): Holds submodules for different LLM providers (openai, gemini, local_ollama) and task logic (task.py).
- Element Finding / UI Interaction:
- Finder Module (clickclickclick/finder): This includes modules for finding required UI elements or context using LLM models (e.g., openai, gemini, mlx, local_ollama).
- Utilities & Auxiliary Functions:
- Files: utils.py, clickclickclick/__init__.py, and the project-level configuration files (pyproject.toml, requirements.txt).

##### Relationships and Interactions
- The entry points (CLI, API, and web interface) initiate task requests.
- Input tasks are passed to the Planner module which decides which model to use and formulates the task plan.
- The Controller then uses Finder modules to locate interface elements or application-specific components (for Android or OSX).
- The Executor then carries out the plan by interacting with the respective platform’s components (through adb or desktop interactions).
- Configurations from YAML files guide both the planner (e.g., selecting which LLM to use) and the executor (e.g., choosing Android vs. OSX specifics).

##### Recognize Architectural Patterns and Design Principles
- Separation of Concerns: Different modules handle planning, finding, and executing tasks.
- Modular Design: Each significant function area (configuration, planning, executing, finding) is encapsulated within its own package or module.
- Extensibility: The use of configuration files (YAML) and multiple interchangeable planner/finder executors enables easy switching of models and platforms.
- Multi-Interface Support: The project supports CLI, Gradio-based web UI, and API access – highlighting a layered architecture to cater to different usage modes.

##### Guidance on Technologies and Frameworks
- The project relies on Python 3.11 and uses standard module structuring.
- It leverages Gradio for a web user interface.
- It uses Uvicorn (ASGI server) to run the API.
- Model integrations include OpenAI, Gemini, and local models via Ollama.
- Additionally, adb is required for Android interactions.

##### Elements
- Adding annotations that detail supported platforms (Android, OSX) and options for model selection (openai, gemini, ollama).
- Optionally, include deployment elements such as Uvicorn for API and Gradio for the web UI as supportive infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        E1["CLI: main.py"]:::entry
        E2["CLI: interface.py"]:::entry
        E3["CLI: Executable (clickclickclick)"]:::entry
        E4["Web Interface (Gradio)"]:::entry
        E5["API: api.py"]:::entry
    end

    %% Aggregate User Request Node
    R["User Request"]:::entry

    %% Connect Entry Points to User Request
    E1 --> R
    E2 --> R
    E3 --> R
    E4 --> R
    E5 --> R

    %% Task Planning & Model Interaction Subgraph
    subgraph "Task Planning & Model Interaction"
        P1["Directory: clickclickclick/planner"]:::logic
        P2["openai.py"]:::logic
        P3["gemini.py"]:::logic
        P4["local_ollama.py"]:::logic
        P5["task.py"]:::logic
    end

    %% Element Finding / UI Interaction Subgraph
    subgraph "Element Finding / UI Interaction"
        F1["Directory: clickclickclick/finder"]:::logic
        F2["openai.py"]:::logic
        F3["gemini.py"]:::logic
        F4["mlx.py"]:::logic
        F5["local_ollama.py"]:::logic
    end

    %% Task Execution Components Subgraph
    subgraph "Task Execution Components"
        X1["Directory: clickclickclick/executor"]:::logic
        X2["android.py"]:::logic
        X3["osx.py"]:::logic
    end

    %% Configuration Management Subgraph
    subgraph "Configuration Management"
        C1["Directory: clickclickclick/config"]:::config
        C2["models.yaml"]:::config
        C3["prompts.yaml"]:::config
        C4["yaml_loader.py"]:::config
        subgraph "Function Declarations"
            CF1["android.yaml"]:::config
            CF2["common.yaml"]:::config
            CF3["osx.yaml"]:::config
        end
    end

    %% Utilities & Auxiliary Functions Subgraph
    subgraph "Utilities & Auxiliary Functions"
        U1["utils.py"]:::utility
        U2["__init__.py"]:::utility
        U3["pyproject.toml"]:::utility
        U4["requirements.txt"]:::utility
    end

    %% Main Flow Connections
    R --> P1
    P1 --> F1
    F1 --> X1

    %% Configuration and Utilities Feeding Core Modules
    C1 ---|"settings"| P1
    C1 ---|"settings"| X1
    U1 ---|"utility"| P1

    %% Class Definitions for Colours
    classDef entry fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef logic fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef config fill:#FFFFE0,stroke:#000,stroke-width:1px;
    classDef utility fill:#F08080,stroke:#000,stroke-width:1px;

    %% Click Events for Entry Points
    click E1 "https://github.com/bandarlabs/clickclickclick/blob/main/main.py"
    click E2 "https://github.com/bandarlabs/clickclickclick/blob/main/interface.py"
    click E3 "https://github.com/bandarlabs/clickclickclick/tree/main/clickclickclick"
    click E5 "https://github.com/bandarlabs/clickclickclick/blob/main/api.py"

    %% Click Events for Task Planning & Model Interaction
    click P1 "https://github.com/bandarlabs/clickclickclick/tree/main/clickclickclick/planner"
    click P2 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/planner/openai.py"
    click P3 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/planner/gemini.py"
    click P4 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/planner/local_ollama.py"
    click P5 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/planner/task.py"

    %% Click Events for Element Finding / UI Interaction
    click F1 "https://github.com/bandarlabs/clickclickclick/tree/main/clickclickclick/finder"
    click F2 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/finder/openai.py"
    click F3 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/finder/gemini.py"
    click F4 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/finder/mlx.py"
    click F5 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/finder/local_ollama.py"

    %% Click Events for Task Execution Components
    click X1 "https://github.com/bandarlabs/clickclickclick/tree/main/clickclickclick/executor"
    click X2 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/executor/android.py"
    click X3 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/executor/osx.py"

    %% Click Events for Configuration Management
    click C1 "https://github.com/bandarlabs/clickclickclick/tree/main/clickclickclick/config"
    click C2 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/config/models.yaml"
    click C3 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/config/prompts.yaml"
    click C4 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/config/yaml_loader.py"
    click CF1 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/config/function_declarations/android.yaml"
    click CF2 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/config/function_declarations/common.yaml"
    click CF3 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/config/function_declarations/osx.yaml"

    %% Click Events for Utilities & Auxiliary Functions
    click U1 "https://github.com/bandarlabs/clickclickclick/blob/main/utils.py"
    click U2 "https://github.com/bandarlabs/clickclickclick/blob/main/clickclickclick/__init__.py"
    click U3 "https://github.com/bandarlabs/clickclickclick/blob/main/pyproject.toml"
    click U4 "https://github.com/bandarlabs/clickclickclick/blob/main/requirements.txt"
```
