# gopeedlab/gopeed architecture

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

- Interactive diagram: https://gitdiagram.com/gopeedlab/gopeed
- Repository: https://github.com/gopeedlab/gopeed

## Overview

Gopeed is a cross-platform download manager: a user submits a resource through a client or automation interface, the core manages a task, protocol fetchers retrieve its content, and the result is saved locally. The graph also preserves the product’s extension runtime, MCP and REST interfaces, CLI, and post-download capabilities. Relationships come from the README and shown source references; dashed links mark documented capabilities or wiring not visible in the sampled excerpts.

Main entry points: [`pkg/download/downloader.go`](https://github.com/gopeedlab/gopeed/blob/main/pkg/download/downloader.go) (Downloader), [`pkg/rest/server.go`](https://github.com/gopeedlab/gopeed/blob/main/pkg/rest/server.go) (REST server), [`internal/fetcher/fetcher.go`](https://github.com/gopeedlab/gopeed/blob/main/internal/fetcher/fetcher.go) (Fetcher registry), [`pkg/api/service.go`](https://github.com/gopeedlab/gopeed/blob/main/pkg/api/service.go) (Task API service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and entrypoints"]
  node_flutter["Flutter clients"]
  node_mobileffi["Mobile FFI<br/>[main.go]"]
  node_cli["CLI downloader<br/>[main.go]"]
  node_webui["Web UI server"]
  node_iosactivity["iOS task activity"]
  node_iosattributes["Activity attributes"]
  node_iosmanager["Live Activity manager"]
  node_iostaskevent["iOS task events"]
  node_windowsrunner["Windows Flutter runner<br/>[flutter_window.h]"]
end

subgraph group_interfaces["APIs and automation"]
  node_rest["REST server<br/>[server.go]"]
  node_api["Task API service<br/>[service.go]"]
  node_mcp["MCP tools<br/>[server.go]"]
  node_events["Task events<br/>[events.go]"]
end

subgraph group_core["Task management"]
  node_model["Task and resource model<br/>[model.go]"]
  node_downloader["Downloader<br/>[downloader.go]"]
  node_storage[("Task storage<br/>[storage.go]")]
end

subgraph group_transfer["Transfer and extensions"]
  node_fetcher["Fetcher registry<br/>[fetcher.go]"]
  node_http["HTTP and HTTPS"]
  node_torrent["BitTorrent"]
  node_ed2k["ED2K"]
  node_ftp["FTP"]
  node_hls["HLS"]
  node_extension["Extension engine<br/>[engine.go]"]
  node_blob["Blob registry<br/>[registry.go]"]
  node_webview["Extension WebView"]
end

subgraph group_results["Files and lifecycle"]
  node_files["Downloaded files"]
  node_lifecycle["Archive and hooks"]
end

node_user(("User"))

node_user -->|"uses"| node_flutter
node_flutter -.->|"calls via FFI"| node_mobileffi
node_mobileffi -->|"starts service"| node_rest
node_user -->|"runs"| node_cli
node_cli -->|"creates task"| node_downloader
node_user -.->|"uses"| node_webui
node_webui -.->|"starts server"| node_rest
node_user -.->|"calls API"| node_rest
node_rest -->|"routes requests"| node_api
node_rest -->|"serves MCP"| node_mcp
node_api -->|"manages tasks"| node_downloader
node_mcp -->|"manages tasks"| node_downloader
node_downloader -->|"uses"| node_model
node_downloader -.->|"persists tasks"| node_storage
node_downloader -.->|"dispatches protocols"| node_fetcher
node_fetcher -->|"builds fetchers"| node_http
node_fetcher -->|"builds fetchers"| node_ftp
node_fetcher -->|"builds fetchers"| node_hls
node_downloader -.->|"supports protocol"| node_torrent
node_downloader -.->|"supports protocol"| node_ed2k
node_downloader -.->|"runs extensions"| node_extension
node_extension -->|"creates object URLs"| node_blob
node_extension -->|"creates runtime"| node_webview
node_downloader -.->|"saves downloads"| node_files
node_downloader -.->|"supports post-download"| node_lifecycle
node_api -.->|"publishes task events"| node_events
node_iosactivity -->|"decodes events"| node_iostaskevent
node_iosmanager -->|"uses events"| node_iostaskevent
node_iosmanager -->|"uses attributes"| node_iosattributes
node_iosactivity -.->|"queries task status"| node_api

click node_flutter "https://github.com/gopeedlab/gopeed/tree/main/ui/flutter"
click node_mobileffi "https://github.com/gopeedlab/gopeed/blob/main/bind/mobile/main.go"
click node_cli "https://github.com/gopeedlab/gopeed/blob/main/cmd/gopeed/main.go"
click node_webui "https://github.com/gopeedlab/gopeed/tree/main/cmd/web"
click node_rest "https://github.com/gopeedlab/gopeed/blob/main/pkg/rest/server.go"
click node_api "https://github.com/gopeedlab/gopeed/blob/main/pkg/api/service.go"
click node_mcp "https://github.com/gopeedlab/gopeed/blob/main/pkg/mcpserver/server.go"
click node_events "https://github.com/gopeedlab/gopeed/blob/main/pkg/api/events.go"
click node_model "https://github.com/gopeedlab/gopeed/blob/main/pkg/base/model.go"
click node_downloader "https://github.com/gopeedlab/gopeed/blob/main/pkg/download/downloader.go"
click node_storage "https://github.com/gopeedlab/gopeed/blob/main/pkg/download/storage.go"
click node_fetcher "https://github.com/gopeedlab/gopeed/blob/main/internal/fetcher/fetcher.go"
click node_http "https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/http"
click node_torrent "https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/bt"
click node_ed2k "https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/ed2k"
click node_ftp "https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/ftp"
click node_hls "https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/hls"
click node_extension "https://github.com/gopeedlab/gopeed/blob/main/pkg/download/engine/engine.go"
click node_blob "https://github.com/gopeedlab/gopeed/blob/main/internal/blob/registry.go"
click node_webview "https://github.com/gopeedlab/gopeed/tree/main/internal/webview"
click node_lifecycle "https://github.com/gopeedlab/gopeed/tree/main/pkg/download"
click node_iosactivity "https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/ios/Runner/GopeedContinuedProcessingManager.swift"
click node_iosattributes "https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/ios/Runner/GopeedDownloadAttributes.swift"
click node_iosmanager "https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/ios/Runner/GopeedLiveActivityManager.swift"
click node_iostaskevent "https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/ios/Runner/GopeedTaskEvent.swift"
click node_windowsrunner "https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/windows/runner/flutter_window.h"

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_flutter,node_mobileffi,node_cli,node_webui,node_iosactivity,node_iosattributes,node_iosmanager,node_iostaskevent,node_windowsrunner,node_user toneBlue
class node_rest,node_api,node_mcp,node_events toneAmber
class node_model,node_downloader,node_storage toneMint
class node_fetcher,node_http,node_torrent,node_ed2k,node_ftp,node_hls,node_extension,node_blob,node_webview toneRose
class node_files,node_lifecycle toneIndigo
```

## Components

### Clients and entrypoints

- [Flutter clients](https://github.com/gopeedlab/gopeed/tree/main/ui/flutter): `ui/flutter`
- [Mobile FFI](https://github.com/gopeedlab/gopeed/blob/main/bind/mobile/main.go): `bind/mobile/main.go`
- [CLI downloader](https://github.com/gopeedlab/gopeed/blob/main/cmd/gopeed/main.go): `cmd/gopeed/main.go`
- [Web UI server](https://github.com/gopeedlab/gopeed/tree/main/cmd/web): `cmd/web`
- [iOS task activity](https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/ios/Runner/GopeedContinuedProcessingManager.swift): `ui/flutter/ios/Runner/GopeedContinuedProcessingManager.swift`
- [Activity attributes](https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/ios/Runner/GopeedDownloadAttributes.swift): `ui/flutter/ios/Runner/GopeedDownloadAttributes.swift`
- [Live Activity manager](https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/ios/Runner/GopeedLiveActivityManager.swift): `ui/flutter/ios/Runner/GopeedLiveActivityManager.swift`
- [iOS task events](https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/ios/Runner/GopeedTaskEvent.swift): `ui/flutter/ios/Runner/GopeedTaskEvent.swift`
- [Windows Flutter runner](https://github.com/gopeedlab/gopeed/blob/main/ui/flutter/windows/runner/flutter_window.h): `ui/flutter/windows/runner/flutter_window.h`

### APIs and automation

- [REST server](https://github.com/gopeedlab/gopeed/blob/main/pkg/rest/server.go): `pkg/rest/server.go`
- [Task API service](https://github.com/gopeedlab/gopeed/blob/main/pkg/api/service.go): `pkg/api/service.go`
- [MCP tools](https://github.com/gopeedlab/gopeed/blob/main/pkg/mcpserver/server.go): `pkg/mcpserver/server.go`
- [Task events](https://github.com/gopeedlab/gopeed/blob/main/pkg/api/events.go): `pkg/api/events.go`

### Task management

- [Task and resource model](https://github.com/gopeedlab/gopeed/blob/main/pkg/base/model.go): `pkg/base/model.go`
- [Downloader](https://github.com/gopeedlab/gopeed/blob/main/pkg/download/downloader.go): `pkg/download/downloader.go`
- [Task storage](https://github.com/gopeedlab/gopeed/blob/main/pkg/download/storage.go): `pkg/download/storage.go`

### Transfer and extensions

- [Fetcher registry](https://github.com/gopeedlab/gopeed/blob/main/internal/fetcher/fetcher.go): `internal/fetcher/fetcher.go`
- [HTTP and HTTPS](https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/http): `internal/protocol/http`
- [BitTorrent](https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/bt): `internal/protocol/bt`
- [ED2K](https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/ed2k): `internal/protocol/ed2k`
- [FTP](https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/ftp): `internal/protocol/ftp`
- [HLS](https://github.com/gopeedlab/gopeed/tree/main/internal/protocol/hls): `internal/protocol/hls`
- [Extension engine](https://github.com/gopeedlab/gopeed/blob/main/pkg/download/engine/engine.go): `pkg/download/engine/engine.go`
- [Blob registry](https://github.com/gopeedlab/gopeed/blob/main/internal/blob/registry.go): `internal/blob/registry.go`
- [Extension WebView](https://github.com/gopeedlab/gopeed/tree/main/internal/webview): `internal/webview`

### Files and lifecycle

- **Downloaded files**
- [Archive and hooks](https://github.com/gopeedlab/gopeed/tree/main/pkg/download): `pkg/download`

### Other components

- **User**

## Connections

- User → Flutter clients: uses (evidence: `README.md`)
- Flutter clients → Mobile FFI: calls via FFI (evidence: `README.md`)
- Mobile FFI → REST server: starts service (evidence: `bind/mobile/main.go`)
- User → CLI downloader: runs (evidence: `README.md`)
- CLI downloader → Downloader: creates task (evidence: `cmd/gopeed/main.go`)
- User → Web UI server: uses (evidence: `README.md`)
- Web UI server → REST server: starts server (evidence: `README.md`)
- User → REST server: calls API (evidence: `README.md`)
- REST server → Task API service: routes requests (evidence: `pkg/rest/server.go`)
- REST server → MCP tools: serves MCP (evidence: `pkg/rest/server.go`)
- Task API service → Downloader: manages tasks (evidence: `pkg/api/service.go`)
- MCP tools → Downloader: manages tasks (evidence: `pkg/mcpserver/server.go`)
- Downloader → Task and resource model: uses
- Downloader → Task storage: persists tasks (evidence: `README.md`)
- Downloader → Fetcher registry: dispatches protocols
- Fetcher registry → HTTP and HTTPS: builds fetchers (evidence: `internal/protocol/http/fetcher_manager.go`)
- Fetcher registry → FTP: builds fetchers (evidence: `internal/protocol/ftp/fetcher_manager.go`)
- Fetcher registry → HLS: builds fetchers (evidence: `internal/protocol/hls/fetcher_manager.go`)
- Downloader → BitTorrent: supports protocol (evidence: `README.md`)
- Downloader → ED2K: supports protocol (evidence: `README.md`)
- Downloader → Extension engine: runs extensions (evidence: `README.md`)
- Extension engine → Blob registry: creates object URLs
- Extension engine → Extension WebView: creates runtime
- Downloader → Downloaded files: saves downloads (evidence: `README.md`)
- Downloader → Archive and hooks: supports post-download (evidence: `README.md`)
- Task API service → Task events: publishes task events (evidence: `README.md`)
- iOS task activity → iOS task events: decodes events (evidence: `ui/flutter/ios/Runner/GopeedContinuedProcessingManager.swift`)
- Live Activity manager → iOS task events: uses events (evidence: `ui/flutter/ios/Runner/GopeedLiveActivityManager.swift`)
- Live Activity manager → Activity attributes: uses attributes (evidence: `ui/flutter/ios/Runner/GopeedLiveActivityManager.swift`)
- iOS task activity → Task API service: queries task status
