# maaxyz/maaframework architecture

> Architecture diagram of the GitHub repository maaxyz/maaframework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maaxyz/maaframework
- Repository: https://github.com/maaxyz/maaframework

## Overview

MaaFramework is a cross-platform, image-recognition automation and black-box testing framework. A caller supplies pipeline definitions and connects a controller; resources load and parse the pipeline, the tasker runs recognition and actions against screenshots, and the controller dispatches input to a device or desktop. The repository also exposes language bindings, device/window discovery, agent-based remote access, and recording/replay controllers. Edges follow the sampled runtime behavior and documented capabilities; some subsystem internals are represented by their exact enclosing directories because their source was not sampled.

Main entry points: [`source/MaaFramework/Resource/ResourceMgr.cpp`](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Resource/ResourceMgr.cpp) (Resource manager), [`source/MaaFramework/Tasker/Tasker.cpp`](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Tasker/Tasker.cpp) (Tasker), [`source/MaaFramework/Task/PipelineTask.cpp`](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Task/PipelineTask.cpp) (Pipeline task), [`source/MaaFramework/Controller/ControllerAgent.cpp`](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Controller/ControllerAgent.cpp) (Controller agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Automation runtime"]
  node_framework_api["Framework API<br/>[MaaFramework.cpp]"]
  node_tasker["Tasker<br/>[Tasker.cpp]"]
  node_pipeline_task["Pipeline task<br/>[PipelineTask.cpp]"]
end

subgraph group_vision["Resources and vision"]
  node_resource_mgr["Resource manager<br/>[ResourceMgr.cpp]"]
  node_pipeline_parser["Pipeline parser<br/>[PipelineParser.cpp]"]
  node_vision_engine["Recognition engine"]
  node_resource_assets["Models and templates"]
end

subgraph group_control["Controllers"]
  node_controller_agent["Controller agent"]
  node_control_units["Platform control units"]
end

subgraph group_integration["Integration"]
  node_toolkit["Device discovery"]
  node_bindings["Language bindings"]
end

subgraph group_remote["Remote and replay"]
  node_agent_client["Agent client"]
  node_agent_server["Agent server"]
  node_recorder["Recording controller"]
  node_replayer["Replay controller"]
end

node_developer(("Framework caller"))
node_pipeline["Pipeline definition"]
node_device(("Device or desktop"))

node_developer -->|"calls"| node_framework_api
node_developer -->|"provides"| node_pipeline
node_framework_api -->|"creates and controls"| node_tasker
node_tasker -->|"uses resources"| node_resource_mgr
node_tasker -->|"runs"| node_pipeline_task
node_resource_mgr -->|"parses pipeline"| node_pipeline_parser
node_pipeline -->|"loaded by"| node_resource_mgr
node_pipeline_task -->|"recognizes image"| node_vision_engine
node_resource_mgr -->|"loads assets"| node_resource_assets
node_pipeline_task -->|"dispatches actions"| node_controller_agent
node_controller_agent -->|"forwards control"| node_control_units
node_control_units -->|"captures and inputs"| node_device
node_developer -->|"discovers devices"| node_toolkit
node_developer -.->|"uses API"| node_bindings
node_agent_client -.->|"exchanges messages"| node_agent_server
node_controller_agent -.->|"wrapped by"| node_recorder
node_replayer -.->|"replays input"| node_control_units

click node_framework_api "https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/API/MaaFramework.cpp"
click node_tasker "https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Tasker/Tasker.cpp"
click node_pipeline_task "https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Task/PipelineTask.cpp"
click node_resource_mgr "https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Resource/ResourceMgr.cpp"
click node_pipeline_parser "https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Resource/PipelineParser.cpp"
click node_vision_engine "https://github.com/maaxyz/maaframework/tree/main/source/MaaFramework/Vision"
click node_resource_assets "https://github.com/maaxyz/maaframework/tree/main/source/MaaFramework/Resource"
click node_controller_agent "https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Controller/ControllerAgent.cpp"
click node_toolkit "https://github.com/maaxyz/maaframework/tree/main/source/MaaToolkit"
click node_bindings "https://github.com/maaxyz/maaframework/tree/main/source/binding"
click node_agent_client "https://github.com/maaxyz/maaframework/tree/main/source/MaaAgentClient"
click node_agent_server "https://github.com/maaxyz/maaframework/tree/main/source/MaaAgentServer"
click node_recorder "https://github.com/maaxyz/maaframework/blob/main/source/MaaRecordControlUnit/RecordController.cpp"
click node_replayer "https://github.com/maaxyz/maaframework/tree/main/source/MaaReplayControlUnit/ReplayRecording"

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_framework_api,node_tasker,node_pipeline_task toneBlue
class node_resource_mgr,node_pipeline_parser,node_vision_engine,node_resource_assets toneAmber
class node_controller_agent,node_control_units toneMint
class node_toolkit,node_bindings toneRose
class node_agent_client,node_agent_server,node_recorder,node_replayer,node_developer,node_pipeline,node_device toneIndigo
```

## Components

### Automation runtime

- [Framework API](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/API/MaaFramework.cpp): `source/MaaFramework/API/MaaFramework.cpp`
- [Tasker](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Tasker/Tasker.cpp): `source/MaaFramework/Tasker/Tasker.cpp`
- [Pipeline task](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Task/PipelineTask.cpp): `source/MaaFramework/Task/PipelineTask.cpp`

### Resources and vision

- [Resource manager](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Resource/ResourceMgr.cpp): `source/MaaFramework/Resource/ResourceMgr.cpp`
- [Pipeline parser](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Resource/PipelineParser.cpp): `source/MaaFramework/Resource/PipelineParser.cpp`
- [Recognition engine](https://github.com/maaxyz/maaframework/tree/main/source/MaaFramework/Vision): `source/MaaFramework/Vision`
- [Models and templates](https://github.com/maaxyz/maaframework/tree/main/source/MaaFramework/Resource): `source/MaaFramework/Resource`

### Controllers

- [Controller agent](https://github.com/maaxyz/maaframework/blob/main/source/MaaFramework/Controller/ControllerAgent.cpp): `source/MaaFramework/Controller/ControllerAgent.cpp`
- **Platform control units**

### Integration

- [Device discovery](https://github.com/maaxyz/maaframework/tree/main/source/MaaToolkit): `source/MaaToolkit`
- [Language bindings](https://github.com/maaxyz/maaframework/tree/main/source/binding): `source/binding`

### Remote and replay

- [Agent client](https://github.com/maaxyz/maaframework/tree/main/source/MaaAgentClient): `source/MaaAgentClient`
- [Agent server](https://github.com/maaxyz/maaframework/tree/main/source/MaaAgentServer): `source/MaaAgentServer`
- [Recording controller](https://github.com/maaxyz/maaframework/blob/main/source/MaaRecordControlUnit/RecordController.cpp): `source/MaaRecordControlUnit/RecordController.cpp`
- [Replay controller](https://github.com/maaxyz/maaframework/tree/main/source/MaaReplayControlUnit/ReplayRecording): `source/MaaReplayControlUnit/ReplayRecording`

### Other components

- **Framework caller**
- **Pipeline definition**
- **Device or desktop**

## Connections

- Framework caller → Framework API: calls
- Framework caller → Pipeline definition: provides
- Framework API → Tasker: creates and controls
- Tasker → Resource manager: uses resources
- Tasker → Pipeline task: runs
- Resource manager → Pipeline parser: parses pipeline
- Pipeline definition → Resource manager: loaded by
- Pipeline task → Recognition engine: recognizes image
- Resource manager → Models and templates: loads assets
- Pipeline task → Controller agent: dispatches actions
- Controller agent → Platform control units: forwards control
- Platform control units → Device or desktop: captures and inputs
- Framework caller → Device discovery: discovers devices
- Framework caller → Language bindings: uses API
- Agent client → Agent server: exchanges messages
- Controller agent → Recording controller: wrapped by
- Replay controller → Platform control units: replays input