# fan-weibo/arkperf architecture

> Architecture diagram of the GitHub repository fan-weibo/arkperf, 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/fan-weibo/arkperf
- Repository: https://github.com/fan-weibo/arkperf

## Overview

ArkPerf is an OpenHarmony performance-analysis agent with CLI, TUI, and desktop interfaces. A user task enters a shared application session, where the agent loop consults an LLM and dispatches tools. MCP-backed Python services collect cold-start, memory, CPU, jank, and full-experience measurements; the agent turns their results into an analysis and recommendations. Local file, command, and Harmony tools also support investigation and optimization. The README documents the measurement capabilities; sampled source confirms the MCP bridge and shared session architecture, but not each service’s internal wiring.

Main entry points: [`internal/mcp/conn.go`](https://github.com/fan-weibo/arkperf/blob/main/internal/mcp/conn.go) (MCP client), [`internal/app/app.go`](https://github.com/fan-weibo/arkperf/blob/main/internal/app/app.go) (App assembly), [`internal/kernel/registry.go`](https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/registry.go) (Tool registry), [`internal/kernel/loop.go`](https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/loop.go) (Agent loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["User interfaces"]
  node_cli["CLI<br/>[main.go]"]
  node_tui["TUI<br/>[app.go]"]
  node_desktop["Desktop service<br/>[service.go]"]
  node_vue["Desktop UI<br/>[App.vue]"]
end

subgraph group_runtime["Agent runtime"]
  node_assembly["App assembly<br/>[app.go]"]
  node_session["Session<br/>[app.go]"]
  node_history[("Session store<br/>[session.go]")]
  node_loop["Agent loop<br/>[loop.go]"]
  node_provider["Model provider<br/>[provider.go]"]
  node_registry["Tool registry<br/>[registry.go]"]
  node_report["Analysis report<br/>[loop.go]"]
end

subgraph group_tools["Tool execution"]
  node_mcp["MCP client<br/>[conn.go]"]
  node_local["Local tools<br/>[fs.go]"]
  node_harmony["Harmony tools<br/>[harmony.go]"]
  node_domain["Harmony domain<br/>[toolchain.go]"]
end

subgraph group_measurement["Measurement services"]
  node_cold["Cold-start service"]
  node_memory["Memory service<br/>[memory_server.py]"]
  node_cpu["CPU service<br/>[cpu_server.py]"]
  node_jank["Jank service<br/>[jank_server.py]"]
  node_experience["Experience service<br/>[agent_server.py]"]
end

node_user(("Engineer"))

node_user -->|"submits task"| node_cli
node_user -->|"submits task"| node_tui
node_user -->|"submits task"| node_vue
node_vue -->|"calls service"| node_desktop
node_cli -->|"creates session"| node_assembly
node_tui -->|"uses session"| node_assembly
node_desktop -->|"bootstraps session"| node_assembly
node_assembly -->|"registers tools"| node_registry
node_assembly -->|"attaches services"| node_mcp
node_assembly -->|"creates session"| node_session
node_session -->|"loads and saves"| node_history
node_session -->|"creates runner"| node_loop
node_loop -->|"requests completion"| node_provider
node_loop -->|"dispatches tools"| node_registry
node_registry -->|"dispatches remote tools"| node_mcp
node_registry -->|"dispatches local tools"| node_local
node_registry -->|"dispatches Harmony tools"| node_harmony
node_harmony -->|"uses toolchain"| node_domain
node_mcp -->|"calls tools"| node_cold
node_mcp -->|"calls tools"| node_memory
node_mcp -->|"calls tools"| node_cpu
node_mcp -->|"calls tools"| node_jank
node_mcp -->|"calls tools"| node_experience
node_loop -->|"forms response"| node_report
node_report -->|"presents findings"| node_user

click node_cli "https://github.com/fan-weibo/arkperf/blob/main/cmd/arkperf/main.go"
click node_tui "https://github.com/fan-weibo/arkperf/blob/main/internal/frontend/tui/app.go"
click node_desktop "https://github.com/fan-weibo/arkperf/blob/main/desktop/service.go"
click node_vue "https://github.com/fan-weibo/arkperf/blob/main/desktop/frontend/src/App.vue"
click node_assembly "https://github.com/fan-weibo/arkperf/blob/main/internal/app/app.go"
click node_session "https://github.com/fan-weibo/arkperf/blob/main/internal/app/app.go"
click node_history "https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/session.go"
click node_loop "https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/loop.go"
click node_provider "https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/provider.go"
click node_registry "https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/registry.go"
click node_mcp "https://github.com/fan-weibo/arkperf/blob/main/internal/mcp/conn.go"
click node_local "https://github.com/fan-weibo/arkperf/blob/main/internal/tools/fs.go"
click node_harmony "https://github.com/fan-weibo/arkperf/blob/main/internal/tools/harmony.go"
click node_domain "https://github.com/fan-weibo/arkperf/blob/main/internal/domain/harmony/toolchain.go"
click node_cold "https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/cold_start_server.py"
click node_memory "https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/memory_server.py"
click node_cpu "https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/cpu_server.py"
click node_jank "https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/jank_server.py"
click node_experience "https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/agent_server.py"
click node_report "https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/loop.go"

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_cli,node_tui,node_desktop,node_vue toneBlue
class node_assembly,node_session,node_history,node_loop,node_provider,node_registry,node_report toneAmber
class node_mcp,node_local,node_harmony,node_domain toneMint
class node_cold,node_memory,node_cpu,node_jank,node_experience toneRose
class node_user toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/fan-weibo/arkperf/blob/main/cmd/arkperf/main.go): `cmd/arkperf/main.go`
- [TUI](https://github.com/fan-weibo/arkperf/blob/main/internal/frontend/tui/app.go): `internal/frontend/tui/app.go`
- [Desktop service](https://github.com/fan-weibo/arkperf/blob/main/desktop/service.go): `desktop/service.go`
- [Desktop UI](https://github.com/fan-weibo/arkperf/blob/main/desktop/frontend/src/App.vue): `desktop/frontend/src/App.vue`

### Agent runtime

- [App assembly](https://github.com/fan-weibo/arkperf/blob/main/internal/app/app.go): `internal/app/app.go`
- [Session](https://github.com/fan-weibo/arkperf/blob/main/internal/app/app.go): `internal/app/app.go`
- [Session store](https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/session.go): `internal/kernel/session.go`
- [Agent loop](https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/loop.go): `internal/kernel/loop.go`
- [Model provider](https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/provider.go): `internal/kernel/provider.go`
- [Tool registry](https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/registry.go): `internal/kernel/registry.go`
- [Analysis report](https://github.com/fan-weibo/arkperf/blob/main/internal/kernel/loop.go): `internal/kernel/loop.go`

### Tool execution

- [MCP client](https://github.com/fan-weibo/arkperf/blob/main/internal/mcp/conn.go): `internal/mcp/conn.go`
- [Local tools](https://github.com/fan-weibo/arkperf/blob/main/internal/tools/fs.go): `internal/tools/fs.go`
- [Harmony tools](https://github.com/fan-weibo/arkperf/blob/main/internal/tools/harmony.go): `internal/tools/harmony.go`
- [Harmony domain](https://github.com/fan-weibo/arkperf/blob/main/internal/domain/harmony/toolchain.go): `internal/domain/harmony/toolchain.go`

### Measurement services

- [Cold-start service](https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/cold_start_server.py): `mcp-servers/cold_start_server.py`
- [Memory service](https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/memory_server.py): `mcp-servers/memory_server.py`
- [CPU service](https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/cpu_server.py): `mcp-servers/cpu_server.py`
- [Jank service](https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/jank_server.py): `mcp-servers/jank_server.py`
- [Experience service](https://github.com/fan-weibo/arkperf/blob/main/mcp-servers/agent_server.py): `mcp-servers/agent_server.py`

### Other components

- **Engineer**

## Connections

- Engineer → CLI: submits task
- Engineer → TUI: submits task
- Engineer → Desktop UI: submits task
- Desktop UI → Desktop service: calls service
- CLI → App assembly: creates session
- TUI → App assembly: uses session
- Desktop service → App assembly: bootstraps session
- App assembly → Tool registry: registers tools
- App assembly → MCP client: attaches services
- App assembly → Session: creates session
- Session → Session store: loads and saves
- Session → Agent loop: creates runner
- Agent loop → Model provider: requests completion
- Agent loop → Tool registry: dispatches tools
- Tool registry → MCP client: dispatches remote tools
- Tool registry → Local tools: dispatches local tools
- Tool registry → Harmony tools: dispatches Harmony tools
- Harmony tools → Harmony domain: uses toolchain
- MCP client → Cold-start service: calls tools
- MCP client → Memory service: calls tools
- MCP client → CPU service: calls tools
- MCP client → Jank service: calls tools
- MCP client → Experience service: calls tools
- Agent loop → Analysis report: forms response
- Analysis report → Engineer: presents findings