# x-plug/mobileagent architecture

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

- Interactive diagram: https://gitdiagram.com/x-plug/mobileagent
- Repository: https://github.com/x-plug/mobileagent

## Overview

##### Project Type and Purpose
- The README emphasizes demo links for PC and mobile operation assistants alongside academic citations. The design caters to both self-evolving mobile agents (Mobile-Agent-E) and PC agents with hierarchical planning.

##### File Structure
- At the top level, you have multiple directories (Mobile-Agent-E, Mobile-Agent-v2, Mobile-Agent-v3, Mobile-Agent, PC-Agent). Each of these roughly contains a parallel architecture but may include additional files or slight variant differences.
- Within each variant directory, key modules appear:
- api.py: Likely handles API request interfaces.
- chat.py: Manages conversational or messaging aspects.
- controller.py (and controller_api.py): Acts as the decision or orchestration layer.
- crop.py, icon_localization.py, text_localization.py: Modules for image processing and visual feature extraction.
- prompt.py (present in some variants): Likely handles prompt engineering for agent interactions.
- There are additional directories for data (e.g., sample scenarios, custom tasks) and static assets for front-end elements like CSS, JS, images, videos, and PDFs.
- Various run scripts (e.g., run.py, run_task.sh) support launching the system or performing tasks.

##### Key Components & Their Relationships
- Main Components to Include:
- Data & Assets: Identify a component handling static resources and data (data, static folders) that feed resources such as configuration files, scenario JSONs, videos, and demos.
- Execution Scripts: A separate “entry point” or “launcher” component representing run scripts and shell scripts which serve as the starting point for the applications.
- Configuration & Dependencies: Although not central to the runtime architecture, include a sub-component for configuration files (e.g., .gitignore, requirements.txt, config.json) that govern build and deployment.

- Relationships and Data Flow:
- Data flow between the Data/Assets component and the agent core modules (illustrating how external configuration, multimedia resources, and scenario JSON files support agent operations).
- For PC-Agent, highlight cross-platform interactions (e.g., integration with Mac and Windows-specific tools).

##### Architectural Patterns and Design Principles
- Hierarchical, modular design. The system is built as a collection of loosely coupled modules (API, controller, visual processing) that together form a multi-agent framework for complex task automation.
- The modular approach implies that each agent variant can be depicted as an encapsulated system, with shared common modules (e.g., similar module names across Mobile-Agent and PC-Agent) but perhaps different configurations and runtime contexts.
- Separation between the “logic layer” (controller, prompt, API, chat) and the “presentation/resource layer” (static assets, videos, demos).

##### Final Recommendation
- Within each variant, break down components into:
- Interface/Entry Point (run scripts, web front-end for demos)
- Core logic (API, chat, controller, prompt, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Mobile-Agent Ecosystem"
        %% Mobile-Agent-E Variant
        subgraph "Mobile-Agent-E"
            MAE_Core["\"API, Chat, Controller, Crop, Icon Localization, Text Localization\""]:::core
            MAE_Run["\"Execution: run.py & scripts\""]:::execution
            MAE_Data["\"Data: scenario JSONs & static assets\""]:::assets
            MAE_Run -->|"triggers"| MAE_Core
            MAE_Core -->|"uses"| MAE_Data
        end

        %% Mobile-Agent-v2 Variant
        subgraph "Mobile-Agent-v2"
            MAv2_Core["\"API, Chat, Controller, Crop, Icon Localization, Text Localization, Prompt\""]:::core
            MAv2_Run["\"Execution: run.py\""]:::execution
            MAv2_Assets["\"Assets: folder assets\""]:::assets
            MAv2_Run -->|"triggers"| MAv2_Core
            MAv2_Core -->|"uses"| MAv2_Assets
        end

        %% Mobile-Agent (qwen variant)
        subgraph "Mobile-Agent (qwen variant)"
            MAQ_Core["\"API, Chat, Controller, Crop, Icon Localization, Text Localization, Prompt\""]:::core
            MAQ_Run["\"Execution: run.py & alternatives\""]:::execution
            MAQ_Assets["\"Assets: folder assets\""]:::assets
            MAQ_Run -->|"triggers"| MAQ_Core
            MAQ_Core -->|"uses"| MAQ_Assets
        end

        %% Mobile-Agent (Alternate)
        subgraph "Mobile-Agent (Alternate)"
            MAlt_Core["\"API, API Service, Chat, Controller, Controller API, Crop, Icon Localization, Prompt, Text Localization\""]:::core
            MAlt_Run["\"Execution: run scripts\""]:::execution
            MAlt_Run -->|"triggers"| MAlt_Core
        end

        %% PC-Agent Variant
        subgraph "PC-Agent"
            subgraph "Primary Core"
                PCA_Core["\"API, Chat, Crop, Icon Localization, Merge Strategy, Prompt Qwen, Text Localization, Text Localization_old\""]:::core
            end
            subgraph "Variant Core"
                PCA_V1_Core["\"API, Chat, Crop, Icon Localization, Merge Strategy, Prompt, Text Localization, Demo Assets\""]:::core
            end
            PCA_Run["\"Execution: run.py & run_v1.py\""]:::execution
            PCA_Run -->|"triggers"| PCA_Core
            PCA_Run -->|"triggers"| PCA_V1_Core
        end

        %% Shared Components
        subgraph "Shared Components"
            Data_Global["\"Global Assets: index.html, static assets\""]:::assets
            Config_Files["\"Config & Dependencies\""]:::config
            External["\"External Services: HuggingFace, ModelScope, YouTube, Bilibili, AcademicPapers\""]:::external
        end

        %% Interactions between core modules and shared components
        MAE_Core -->|"requires"| Data_Global
        MAv2_Core -->|"requires"| Data_Global
        MAQ_Core -->|"requires"| Data_Global
        MAlt_Core -->|"requires"| Data_Global
        PCA_Core -->|"requires"| Data_Global
        PCA_V1_Core -->|"requires"| Data_Global

        MAE_Core -->|"reads"| Config_Files
        MAv2_Core -->|"reads"| Config_Files
        MAQ_Core -->|"reads"| Config_Files
        MAlt_Core -->|"reads"| Config_Files
        PCA_Core -->|"reads"| Config_Files
        PCA_V1_Core -->|"reads"| Config_Files

        %% External integrations connections
        MAE_Run -->|"integrates"| External
        MAv2_Run -->|"integrates"| External
        MAQ_Run -->|"integrates"| External
        PCA_Run -->|"integrates"| External
    end

    %% Click Events
    click MAE_Core "https://github.com/x-plug/mobileagent/tree/main/Mobile-Agent-E/MobileAgentE"
    click MAv2_Core "https://github.com/x-plug/mobileagent/tree/main/Mobile-Agent-v2/MobileAgent"
    click MAQ_Core "https://github.com/x-plug/mobileagent/tree/main/Mobile-Agent/Mobile-Agent-qwen/MobileAgent"
    click MAlt_Core "https://github.com/x-plug/mobileagent/tree/main/Mobile-Agent/MobileAgent"
    click PCA_Core "https://github.com/x-plug/mobileagent/tree/main/PC-Agent/PCAgent"
    click PCA_V1_Core "https://github.com/x-plug/mobileagent/tree/main/PC-Agent/PCAgent_v1"
    click MAE_Data "https://github.com/x-plug/mobileagent/tree/main/Mobile-Agent-E/data"
    click MAv2_Assets "https://github.com/x-plug/mobileagent/tree/main/Mobile-Agent-v2/assets"
    click MAQ_Assets "https://github.com/x-plug/mobileagent/tree/main/Mobile-Agent/assets"
    click MAE_Run "https://github.com/x-plug/mobileagent/blob/main/Mobile-Agent-E/run.py"
    click MAv2_Run "https://github.com/x-plug/mobileagent/blob/main/Mobile-Agent-v2/run.py"
    click MAQ_Run "https://github.com/x-plug/mobileagent/blob/main/Mobile-Agent/Mobile-Agent-qwen/run.py"
    click PCA_Run "https://github.com/x-plug/mobileagent/blob/main/PC-Agent/run.py"
    click Config_Files "https://github.com/x-plug/mobileagent/blob/main/PC-Agent/config.json"

    %% Styles
    classDef core fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef execution fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef assets fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef config fill:#F5B7B1,stroke:#CB4335,stroke-width:2px;
```
