# cmdragon/dratk architecture

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

- Interactive diagram: https://gitdiagram.com/cmdragon/dratk
- Repository: https://github.com/cmdragon/dratk

## Overview

##### 先说明：从仓库内容能/不能推断什么
从你提供的 `<file_tree>` 来看，这个仓库几乎只有：
- `.github/*`（issue 模板、funding）
- `README.md`
- `docs/images`（可能是截图/说明图）

没有 `src/`, `package.json`, `Cargo.toml`, `pubspec.yaml`, `go.mod` 等源码与构建配置，因此**无法从文件树确定技术栈（Electron/Tauri/Flutter/.NET 等）和真实模块边界**。
但 README 描述非常清晰：DraTK 是一个**跨平台桌面应用**，有**模块化/插件化工具集合**、**主题/多语言**、**自动更新**、**认证**、**通知/窗口状态**等“应用级基础设施”。
因此系统设计图应围绕“桌面应用壳 + 核心平台能力 + 工具插件 + 外部依赖（文件系统、更新服务、认证服务等）”来画。

##### 项目类型与目的（在图里要体现）
**类型**：跨平台桌面端工具集（Toolbox Desktop App），强调插件化扩展。
**目的**：对本地文件系统做批量整理/清理/结构变换，并提供现代 UI、可撤销、可预览、报告/统计、自动更新、登录认证等能力。

在架构图中，你要让读者一眼看到：

##### 建议采用的画图方法：C4 + 关键流程图（最准确、最不容易过度脑补）
对 Principal 级别最有效的是组合：
##### 2~4 张关键 Sequence/Activity 图：预览整理、执行、撤销、更新等关键链路

> 在缺少源码的情况下，不要假设具体语言/框架；但可以把“UI 渲染层”和“本地能力层（文件系统/更新/存储）”作为抽象容器画出来。

##### 你需要在图中拆出来的“尽可能多”的组件（按层次）
下面给出一个推荐拆分（你可以直接照此画容器/组件图）。

##### 外部参与者 & 外部系统（Context 图）
- **User（用户）**
- **OS 文件系统（Windows/Linux/macOS FS）**
- **更新分发端（GitHub Releases / Update Manifest/CDN）**
- **认证服务（Auth Provider）**：README 提到登录/登出，但未说明是本地还是远端；图上可先画为外部服务（可替换）
- （可选）**崩溃/日志上报服务**：README 未提，可不画；除非你们产品确实有

**箭头示例**：
- User → DraTK：配置工具参数/执行/撤销/查看报告
- DraTK ↔ OS FS：扫描目录、移动/重命名/删除、读取元数据
- DraTK ↔ Update Service：检查版本、下载、校验、安装、回滚
- DraTK ↔ Auth Provider：登录、token/会话校验、登出

##### “容器级”内部结构（Container 图）
把桌面应用画成 2~4 个大容器（不要纠结具体技术实现）：

##### Desktop UI Shell（桌面 UI 壳）
- 导航（侧边栏/多标签）
- 设置页面（语言/主题/通知/更新）
- 任务页（各工具 UI）
- 进度与结果展示（统计、详细列表、报告视图）

##### Core Application Runtime（核心运行时/平台层）
- 插件/工具加载器（动态加载工具模块）
- 任务编排与并发（异步执行、避免 UI 卡顿）
- 统一权限/安全策略（避免误删、根目录保留等策略）
- 日志与审计（为撤销/报告提供事件来源）

##### Local Services（本地服务层）
- **File System Service**：扫描、过滤、移动、重命名、删除、冲突处理、特殊字符处理
- **History & Undo Service**：操作记录、撤销/回滚（工具 3/4 明确需要）
- **Report Service**：生成整理报告/清理统计
- **Settings Store**：语言、主题、通知开关、更新渠道、窗口状态
- **Window State Manager**：保存/恢复窗口大小位置
- **Notification Service**：toast/系统通知/重要提醒

##### Update & Security（更新与安全子系统）
- Update Checker（启动时/手动检查）
- Downloader（断点/重试可选）
- Integrity Verifier（SHA256 校验）
- Backup Manager（更新前备份）
- Installer/Applier（替换文件、重启）
- Rollback Manager（失败回滚）
- Channel Manager（稳定/测试）

##### （可选）Auth Module（认证模块）
- Login UI
- Credential Storage（系统 keychain/加密存储，具体未知可抽象）
- Session Manager（token 刷新、登出）

> 这些“容器/子系统”之间的箭头要明确：UI 只发起命令与订阅状态；真正的文件变更只在本地服务层执行。

##### “工具插件层”的组件拆分（Component 图里重点表达模块化）
根据 README 的四个工具，把它们统一成一个接口/抽象：

- **Tool Plugin Interface（工具插件接口）**
- `configure()` / `validate()`
- `preview()`（有预览的工具）
- `execute()`（执行）
- `emitProgress()`（进度事件）
- `result()`（结构化结果：成功/跳过/错误）
- `undo()`（可撤销工具必须实现）
- **Tool: 文件整理专家**
- Rule Engine（类型/时间/大小/自定义规则）
- Preview Planner（预览输出：目标路径、冲突、统计）
- Executor（批量移动/归档）
- **Tool: 空目录清理**
- Directory Scanner（空目录判定）
- Tree Model Builder（树形展示数据）
- Delete Executor（保留根目录策略）
- **Tool: 文件夹解散**
- Depth Controller（处理深度 1-10）
- Filter（扩展名过滤）
- Flatten Executor（移动/重命名冲突处理）
- Undo Adapter（写入历史）
- **Tool: 文件套文件夹**
- Folderizer（创建同名目录并移动文件）
- Sanitizer（特殊字符处理）
- Undo Adapter（写入历史）

**重要：工具不要直接操作 UI 和存储**
图里用依赖箭头表达：Tool Plugin → File System Service / History Service / Report Service；UI 通过 Core Runtime 调度工具。

##### 关键交互关系（你必须画出来的“箭头”和数据流）
为了“最准确”，建议在容器图/组件图上至少标出这些主路径：

##### 用户操作 → UI → Core Runtime → Tool Plugin → Local Services → OS FS
- UI 只负责收集参数/展示状态
- Runtime 负责任务生命周期（开始/取消/并发/错误）
- Tool 负责业务规则
- Local Services 才落盘

##### 执行前预览链路（文件整理专家最关键）
- Tool.preview() → File System Service（扫描/元数据） → Preview Planner → UI（展示预览 + 统计）
- 预览结果应可序列化：供“开始整理”复用/对比（可在图上标注）

##### 撤销链路（工具 3/4 明确要求）
- Execute 时：每一步文件变更 → History Service 记录“反向操作”
- Undo：History Service 重放反向操作 → File System Service → OS FS
- UI：展示撤销进度/结果

##### 自动更新链路（README 描述很完整，值得单独画一张序列图）
- App Start → Update Checker → 拉取 manifest/最新版本 → UI 通知
- 用户确认 → Downloader → Integrity Verifier（SHA256）
- 通过 → Backup Manager → Installer → 重启
- 失败 → Rollback Manager → 恢复旧版本 → 通知

##### 设置/个性化链路
- Settings UI → Settings Store（持久化）
- i18n/Theme Engine 订阅设置变化 → UI 立即刷新（README 提到实时更新）

##### 按“桌面工具集 + 插件化”的特点，图要特别强调的架构原则
- **横切能力平台化**：i18n、主题、通知、设置、更新、认证、撤销/历史、报告 都是“平台能力”，工具只是消费它们
- **文件操作的安全边界**：所有 destructive 操作（删除/移动）集中在 File System Service，并有统一的策略（根目录保留、冲突命名、权限错误处理）
- **异步任务与 UI 解耦**：用“任务队列/worker/后台执行”的概念画出来，解释“避免界面卡顿”的来源
- **插件加载边界**：Runtime 通过注册表/manifest 动态加载工具（README 明确提到动态加载插件）

##### 画图规范（让图可读、可审阅、可落地）
- 每个框：**名称 + 职责一句话 + 关键数据/接口**（例如 `History Service: store reversible operations`）
- 箭头：写清楚**协议/方式**（如 “in-process call / event bus / filesystem API / HTTPS”——如果未知就写 “API call”）
- 数据：用小标签标出核心数据结构
- 预览计划（Preview Plan）
- 操作历史（Operation Log）
- 设置（Settings）
- 更新清单（Manifest）/安装包（Package）

##### 颜色/形状建议（强制区分类型）
- 蓝色：UI 层
- 绿色：核心运行时/编排层
- 橙色：本地服务（FS/设置/历史/报告）
- 紫色：工具插件
- 灰色：外部系统（OS、更新服务、认证服务）

##### Component 图（1~2 张）：
- 平台层组件（FS/History/Report/Settings/i18n/Theme/Notification/WindowState/TaskManager）
- 插件层组件（四个工具 + Tool Plugin Interface）
##### Sequence 图（至少 2 张）：
- 文件整理专家：预览→执行→报告
- 自动更新：检查→下载→校验→备份→安装→回滚
（可选再加：撤销流程、空目录清理删除策略）

##### 你现在缺的关键信息（为了把图从“合理”变成“精确”）
如果你能从源码/构建文件补充以下内容，图的准确度会显著提升：
- 技术栈：Electron/Tauri/Flutter/.NET/Qt？是否多进程（UI/后台）？
- 插件机制：动态加载是通过脚本、动态库、还是编译期模块注册？
- 设置与历史的存储：本地文件（JSON/SQLite）还是系统注册表/Keychain？
- 自动更新实现：自研 updater 还是框架自带（如 Squirrel、Sparkle、Tauri updater）？
- 认证：纯本地还是远程账号体系？token 生命周期与存储方式？

如果你把真实源码目录结构（例如 `src/`, `app/`, `packages/`）补上，我可以把上面的“抽象容器/组件”进一步落到**具体模块名、入口文件、依赖方向**，并给出更贴近实现的 C4 Component 图拆分建议。

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% System Context (C4-Context)
  %% =========================
  subgraph "System Context (C4)"
    U["User\n- Configures tools\n- Runs preview/execute/undo\n- Views reports"]:::external

    subgraph "DraTK (Cross-platform Desktop Toolbox App)"
      APPCTX["DraTK Desktop App\n- Modular tool plugins\n- Theme/i18n\n- Auto-update\n- Auth\n- Notifications & window state"]:::app
    end

    OSFS[("OS File System\n(Windows/Linux/macOS)")]:::external
    UPD["Update Distribution\n(GitHub Releases / Manifest / CDN)"]:::external
    AUTH["Auth Provider\n(Remote or replaceable)"]:::external
  end

  U -->|"uses"| APPCTX
  APPCTX <-->|"filesystem_API"| OSFS
  APPCTX <-->|"HTTPS(manifest/package)"| UPD
  APPCTX <-->|"login/logout/session"| AUTH

  %% =========================
  %% Container (C4-Container)
  %% =========================
  subgraph "Containers (C4)"
    direction TB

    subgraph "Desktop UI Shell"
      direction TB
      UI["UI Shell\n- Navigation / tool pages\n- Settings\n- Progress & results\n- Report viewer"]:::ui
      SETUI["Settings UI\n- Language/Theme\n- Notifications\n- Update channel\n- Window state"]:::ui
      LOGINUI["Login UI"]:::ui
    end

    subgraph "Core Application Runtime"
      direction TB
      RT["Core Runtime\n- Commands & state\n- Error handling\n- Security policies"]:::core
      TM["Task Manager / Orchestrator\n- Async jobs\n- Concurrency\n- Cancel"]:::core
      PL["Plugin/Tool Loader\n- Registry/manifest\n- Dynamic loading"]:::core
      EB["Event Bus / State Store\n- Progress events\n- UI subscriptions"]:::core
      AUD["Logging & Audit\n- Event source for reports/undo"]:::core
    end

    subgraph "Tool Plugins (Extensible)"
      direction TB
      TPI["Tool Plugin Interface\nconfigure/validate\npreview/execute\nemitProgress/result\nundo(optional)"]:::plugin

      subgraph "Built-in Tools"
        direction TB
        T1["Tool: File Organizer Expert\n- Rule engine\n- Preview planner\n- Executor(move/archive)"]:::plugin
        T2["Tool: Empty Folder Cleaner\n- Directory scanner\n- Tree model\n- Delete executor(root protected)"]:::plugin
        T3["Tool: Folder Dissolver\n- Depth controller(1-10)\n- Extension filter\n- Flatten executor\n- Undo adapter"]:::plugin
        T4["Tool: File-to-Folder\n- Folderizer\n- Sanitizer\n- Undo adapter"]:::plugin
      end
    end

    subgraph "Local Services"
      direction TB
      FS["File System Service\n- Scan/filter\n- Move/rename/delete\n- Conflict handling\n- Special chars\n- Safety policies"]:::local
      HIS["History & Undo Service\n- Operation log\n- Replay inverse ops"]:::local
      REP["Report Service\n- Cleanup stats\n- Organize reports\n- Structured results"]:::local
      ST["Settings Store\n- Persist settings\n- Update channel\n- Preferences"]:::local
      WS["Window State Manager\n- Save/restore size/pos"]:::local
      NOTIF["Notification Service\n- Toast/system notifications\n- Important prompts"]:::local
      I18N["i18n Engine\n- Live language switching"]:::local
      THEME["Theme Engine\n- Live theme switching"]:::local
      CRED["Credential Storage\n- Keychain/encrypted store(abstract)"]:::local
      SESS["Session Manager\n- Token/session\n- Refresh/logout"]:::local
    end

    subgraph "Update & Security Subsystem"
      direction TB
      UC["Update Checker\n- Startup/manual check"]:::update
      CM["Channel Manager\n- Stable/Beta"]:::update
      DL["Downloader\n- Retry/resume(optional)"]:::update
      IV["Integrity Verifier\n- SHA256 verify"]:::update
      BK["Backup Manager\n- Pre-update backup"]:::update
      IN["Installer/Applier\n- Replace binaries\n- Restart"]:::update
      RB["Rollback Manager\n- Restore on failure"]:::update
    end
  end

  %% Container connections (vertical + explicit boundaries)
  UI -->|"commands"| RT
  SETUI -->|"update_preferences"| ST
  SETUI -->|"apply_language"| I18N
  SETUI -->|"apply_theme"| THEME
  SETUI -->|"toggle_notifications"| NOTIF
  SETUI -->|"save_window_state"| WS

  LOGINUI -->|"login/logout"| SESS
  SESS <-->|"store/retrieve"| CRED
  SESS -->|"session_state"| EB
  RT -->|"auth_required_ops"| SESS

  RT -->|"enqueue_job"| TM
  TM -->|"publish_progress"| EB
  EB -->|"render_state"| UI

  RT -->|"load_tools"| PL
  PL -->|"registers"| TPI
  TPI -->|"implements"| T1
  TPI -->|"implements"| T2
  TPI -->|"implements"| T3
  TPI -->|"implements"| T4

  RT -->|"invoke_tool_calls"| TPI
  T1 -->|"filesystem_ops"| FS
  T2 -->|"filesystem_ops"| FS
  T3 -->|"filesystem_ops"| FS
  T4 -->|"filesystem_ops"| FS

  T1 -->|"report_data"| REP
  T2 -->|"report_data"| REP
  T3 -->|"report_data"| REP
  T4 -->|"report_data"| REP

  T3 -->|"record_inverse_ops"| HIS
  T4 -->|"record_inverse_ops"| HIS
  HIS -->|"replay_undo_ops"| FS

  RT -->|"audit_events"| AUD
  AUD -->|"inputs"| HIS
  AUD -->|"inputs"| REP

  FS -->|"OS_calls"| OSFS
  NOTIF -->|"system_notify"| U

  %% Update subsystem wiring
  RT -->|"check_for_updates"| UC
  UC -->|"use_channel"| CM
  UC -->|"fetch_manifest"| UPD
  UC -->|"update_available_event"| EB
  UI -->|"user_confirms_update"| RT
  RT -->|"start_update"| DL
  DL -->|"download_package"| UPD
  DL -->|"verify"| IV
  IV -->|"ok"| BK
  BK -->|"apply_update"| IN
  IN -->|"restart_app"| RT
  IV -->|"failed"| RB
  IN -->|"failed"| RB
  RB -->|"notify_failure"| NOTIF

  %% =========================
  %% Key Flows (Activity-like callouts)
  %% =========================
  subgraph "Key Flows (Summary)"
    direction TB
    P1["Preview Flow (Organizer)\nUI → Runtime → Tool.preview()\n→ FS scan/metadata → Preview Plan\n→ UI shows plan & stats"]:::note
    P2["Execute & Report Flow\nUI → Runtime → Tool.execute()\n→ FS changes → Report Service\n→ UI shows results"]:::note
    P3["Undo Flow (Tools 3/4)\nExecute writes inverse ops to History\nUndo replays inverse ops → FS → OS"]:::note
    P4["Auto Update Flow\nCheck → Manifest → Download\n→ SHA256 verify → Backup\n→ Install & restart\n→ Rollback on failure"]:::note
  end

  UI -->|"preview_execute_undo"| P1
  UI -->|"execute"| P2
  UI -->|"undo"| P3
  UI -->|"update"| P4

  %% =========================
  %% Dummy nodes to attach clicks for repo artifacts without polluting architecture
  %% =========================
  subgraph "Repository Artifacts (Docs & Collaboration)"
    direction TB
    DOCS["docs/ (Documentation)"]:::repo
    IMGS["docs/images/ (Screenshots/Diagrams)"]:::repo
    BUG["Bug report template"]:::repo
    FEAT["Feature request template"]:::repo
    FUND["Funding config"]:::repo
  end

  %% keep artifacts visually separate but vertical
  APPCTX -->|"docs/reference"| DOCS

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click APPCTX "https://github.com/cmdragon/dratk/blob/main/README.md"
  click UI "https://github.com/cmdragon/dratk/blob/main/README.md"
  click RT "https://github.com/cmdragon/dratk/blob/main/README.md"
  click TPI "https://github.com/cmdragon/dratk/blob/main/README.md"
  click UC "https://github.com/cmdragon/dratk/blob/main/README.md"
  click SESS "https://github.com/cmdragon/dratk/blob/main/README.md"

  click P1 "https://github.com/cmdragon/dratk/blob/main/README.md"
  click P2 "https://github.com/cmdragon/dratk/blob/main/README.md"
  click P3 "https://github.com/cmdragon/dratk/blob/main/README.md"
  click P4 "https://github.com/cmdragon/dratk/blob/main/README.md"

  click SETUI "https://github.com/cmdragon/dratk/blob/main/README.md"
  click LOGINUI "https://github.com/cmdragon/dratk/blob/main/README.md"

  click REP "https://github.com/cmdragon/dratk/blob/main/README.md"
  click HIS "https://github.com/cmdragon/dratk/blob/main/README.md"
  click FS "https://github.com/cmdragon/dratk/blob/main/README.md"

  click DOCS "https://github.com/cmdragon/dratk/tree/main/docs/"
  click IMGS "https://github.com/cmdragon/dratk/tree/main/docs/images/"
  click BUG "https://github.com/cmdragon/dratk/blob/main/.github/ISSUE_TEMPLATE/bug_report.md"
  click FEAT "https://github.com/cmdragon/dratk/blob/main/.github/ISSUE_TEMPLATE/feature_request.md"
  click FUND "https://github.com/cmdragon/dratk/blob/main/.github/FUNDING.yml"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ECEFF1,stroke:#607D8B,stroke-width:1px,color:#263238;
  classDef app fill:#E3F2FD,stroke:#1565C0,stroke-width:2px,color:#0D47A1;
  classDef ui fill:#BBDEFB,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1;
  classDef core fill:#C8E6C9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20;
  classDef local fill:#FFE0B2,stroke:#EF6C00,stroke-width:1.5px,color:#E65100;
  classDef update fill:#E1BEE7,stroke:#6A1B9A,stroke-width:1.5px,color:#4A148C;
  classDef plugin fill:#D1C4E9,stroke:#512DA8,stroke-width:1.5px,color:#311B92;
  classDef note fill:#FFF9C4,stroke:#F9A825,stroke-width:1px,color:#6D4C41;
  classDef repo fill:#F5F5F5,stroke:#9E9E9E,stroke-width:1px,color:#424242;
```
