# d4rken-org/butler architecture

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

- Interactive diagram: https://gitdiagram.com/d4rken-org/butler
- Repository: https://github.com/d4rken-org/butler

## Overview

Butler is an Android file explorer for power users. A user opens parallel workspace tabs, then browses storage, searches files, edits text, or manages apps; file operations include copy, move, deletion and trash. The shared path/gateway layer represents different storage backends, while ADB and Root/Shizuku provide privileged access. The README documents product capabilities; sampled engine and provider excerpts support selected internal links. Other subsystem wiring is not shown, so those links are omitted.

Main entry points: [`app-common-io/src/main/java/eu/darken/butler/common/files/GatewaySwitch.kt`](https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/GatewaySwitch.kt) (Storage gateways), [`app-workspace/src/main/java/eu/darken/butler/workspace/core/Workspace.kt`](https://github.com/d4rken-org/butler/blob/main/app-workspace/src/main/java/eu/darken/butler/workspace/core/Workspace.kt) (Workspace tabs), [`app-workspace-editor/src/main/java/eu/darken/butler/editor/core/engine/EditorEngine.kt`](https://github.com/d4rken-org/butler/blob/main/app-workspace-editor/src/main/java/eu/darken/butler/editor/core/engine/EditorEngine.kt) (Text editor), [`app-common-io/src/main/java/eu/darken/butler/common/files/APath.kt`](https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/APath.kt) (Path model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace and UI"]
  node_workspace["Workspace tabs<br/>[Workspace.kt]"]
  node_explorer["File explorer<br/>[BrowsingEngine.kt]"]
end

subgraph group_fileops["Files and operations"]
  node_operations["File operations<br/>[GenericPathMove.kt]"]
  node_trash["Trash bin<br/>[TrashManager.kt]"]
end

subgraph group_storage["Storage access"]
  node_files["Path model<br/>[APath.kt]"]
  node_gateways["Storage gateways<br/>[GatewaySwitch.kt]"]
  node_lookup["Path lookup<br/>[APathLookup.kt]"]
  node_archives["Archive access<br/>[ArchiveGateway.kt]"]
  node_network["Network storage<br/>[SftpGateway.kt]"]
end

subgraph group_features["Power-user features"]
  node_search["File search<br/>[SearchEngine.kt]"]
  node_editor["Text editor<br/>[EditorEngine.kt]"]
  node_apps["App manager<br/>[AppsEngine.kt]"]
end

subgraph group_platform["Android integration"]
  node_documents["Documents provider"]
  node_adb["ADB access<br/>[AdbServer.kt]"]
end

node_user(("Android user"))
node_android[("Android storage")]
node_rootshizuku(("Root / Shizuku"))

node_user -->|"opens tabs"| node_workspace
node_workspace -->|"opens browser"| node_explorer
node_workspace -->|"opens search"| node_search
node_workspace -->|"opens editor"| node_editor
node_workspace -->|"opens manager"| node_apps
node_search -->|"uses paths"| node_files
node_editor -->|"uses paths"| node_files
node_editor -->|"reads and writes"| node_gateways
node_documents -->|"queries paths"| node_lookup
node_documents -->|"queries storage"| node_gateways
node_files -.->|"routes access"| node_gateways
node_gateways -.->|"accesses storage"| node_android
node_gateways -.->|"supports archives"| node_archives
node_gateways -.->|"supports SFTP"| node_network
node_operations -.->|"deletes to trash"| node_trash
node_adb -.->|"uses privilege"| node_rootshizuku

click node_workspace "https://github.com/d4rken-org/butler/blob/main/app-workspace/src/main/java/eu/darken/butler/workspace/core/Workspace.kt"
click node_explorer "https://github.com/d4rken-org/butler/blob/main/app-workspace-explorer/src/main/java/eu/darken/butler/explorer/core/engine/BrowsingEngine.kt"
click node_search "https://github.com/d4rken-org/butler/blob/main/app-workspace-searcher/src/main/java/eu/darken/butler/searcher/core/engine/SearchEngine.kt"
click node_editor "https://github.com/d4rken-org/butler/blob/main/app-workspace-editor/src/main/java/eu/darken/butler/editor/core/engine/EditorEngine.kt"
click node_apps "https://github.com/d4rken-org/butler/blob/main/app-workspace-apps/src/main/java/eu/darken/butler/apps/core/engine/AppsEngine.kt"
click node_files "https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/APath.kt"
click node_gateways "https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/GatewaySwitch.kt"
click node_lookup "https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/APathLookup.kt"
click node_operations "https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/operations/GenericPathMove.kt"
click node_trash "https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/trash/TrashManager.kt"
click node_archives "https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/archive/ArchiveGateway.kt"
click node_network "https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/sftp/SftpGateway.kt"
click node_documents "https://github.com/d4rken-org/butler/blob/main/app-provider-documents/src/main/java/eu/darken/butler/provider/documents/core/query/DocumentQueryHandler.kt"
click node_adb "https://github.com/d4rken-org/butler/blob/main/app-common-adb/src/main/java/eu/darken/butler/common/adb/shizuku/AdbServer.kt"

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_workspace,node_explorer,node_user toneBlue
class node_operations,node_trash,node_android toneAmber
class node_files,node_gateways,node_lookup,node_archives,node_network toneMint
class node_search,node_editor,node_apps toneRose
class node_documents,node_adb,node_rootshizuku toneIndigo
```

## Components

### Workspace and UI

- [Workspace tabs](https://github.com/d4rken-org/butler/blob/main/app-workspace/src/main/java/eu/darken/butler/workspace/core/Workspace.kt): `app-workspace/src/main/java/eu/darken/butler/workspace/core/Workspace.kt`
- [File explorer](https://github.com/d4rken-org/butler/blob/main/app-workspace-explorer/src/main/java/eu/darken/butler/explorer/core/engine/BrowsingEngine.kt): `app-workspace-explorer/src/main/java/eu/darken/butler/explorer/core/engine/BrowsingEngine.kt`

### Files and operations

- [File operations](https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/operations/GenericPathMove.kt): `app-common-io/src/main/java/eu/darken/butler/common/files/operations/GenericPathMove.kt`
- [Trash bin](https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/trash/TrashManager.kt): `app-common-io/src/main/java/eu/darken/butler/common/trash/TrashManager.kt`

### Storage access

- [Path model](https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/APath.kt): `app-common-io/src/main/java/eu/darken/butler/common/files/APath.kt`
- [Storage gateways](https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/GatewaySwitch.kt): `app-common-io/src/main/java/eu/darken/butler/common/files/GatewaySwitch.kt`
- [Path lookup](https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/APathLookup.kt): `app-common-io/src/main/java/eu/darken/butler/common/files/APathLookup.kt`
- [Archive access](https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/archive/ArchiveGateway.kt): `app-common-io/src/main/java/eu/darken/butler/common/files/archive/ArchiveGateway.kt`
- [Network storage](https://github.com/d4rken-org/butler/blob/main/app-common-io/src/main/java/eu/darken/butler/common/files/sftp/SftpGateway.kt): `app-common-io/src/main/java/eu/darken/butler/common/files/sftp/SftpGateway.kt`

### Power-user features

- [File search](https://github.com/d4rken-org/butler/blob/main/app-workspace-searcher/src/main/java/eu/darken/butler/searcher/core/engine/SearchEngine.kt): `app-workspace-searcher/src/main/java/eu/darken/butler/searcher/core/engine/SearchEngine.kt`
- [Text editor](https://github.com/d4rken-org/butler/blob/main/app-workspace-editor/src/main/java/eu/darken/butler/editor/core/engine/EditorEngine.kt): `app-workspace-editor/src/main/java/eu/darken/butler/editor/core/engine/EditorEngine.kt`
- [App manager](https://github.com/d4rken-org/butler/blob/main/app-workspace-apps/src/main/java/eu/darken/butler/apps/core/engine/AppsEngine.kt): `app-workspace-apps/src/main/java/eu/darken/butler/apps/core/engine/AppsEngine.kt`

### Android integration

- [Documents provider](https://github.com/d4rken-org/butler/blob/main/app-provider-documents/src/main/java/eu/darken/butler/provider/documents/core/query/DocumentQueryHandler.kt): `app-provider-documents/src/main/java/eu/darken/butler/provider/documents/core/query/DocumentQueryHandler.kt`
- [ADB access](https://github.com/d4rken-org/butler/blob/main/app-common-adb/src/main/java/eu/darken/butler/common/adb/shizuku/AdbServer.kt): `app-common-adb/src/main/java/eu/darken/butler/common/adb/shizuku/AdbServer.kt`

### Other components

- **Android user**
- **Android storage**
- **Root / Shizuku**

## Connections

- Android user → Workspace tabs: opens tabs (evidence: `README.md`)
- Workspace tabs → File explorer: opens browser (evidence: `README.md`)
- Workspace tabs → File search: opens search (evidence: `README.md`)
- Workspace tabs → Text editor: opens editor (evidence: `README.md`)
- Workspace tabs → App manager: opens manager (evidence: `README.md`)
- File search → Path model: uses paths (evidence: `app-workspace-searcher/src/main/java/eu/darken/butler/searcher/core/engine/SearchEngine.kt`)
- Text editor → Path model: uses paths (evidence: `app-workspace-editor/src/main/java/eu/darken/butler/editor/core/engine/EditorEngine.kt`)
- Text editor → Storage gateways: reads and writes (evidence: `app-workspace-editor/src/main/java/eu/darken/butler/editor/core/engine/EditorEngine.kt`)
- Documents provider → Path lookup: queries paths (evidence: `app-provider-documents/src/main/java/eu/darken/butler/provider/documents/core/query/DocumentQueryHandler.kt`)
- Documents provider → Storage gateways: queries storage (evidence: `app-provider-documents/src/main/java/eu/darken/butler/provider/documents/core/query/DocumentQueryHandler.kt`)
- Path model → Storage gateways: routes access (evidence: `app-common-io/src/main/java/eu/darken/butler/common/files/GatewaySwitch.kt`)
- Storage gateways → Android storage: accesses storage
- Storage gateways → Archive access: supports archives (evidence: `app-common-io/src/main/java/eu/darken/butler/common/files/GatewaySwitch.kt`)
- Storage gateways → Network storage: supports SFTP (evidence: `app-common-io/src/main/java/eu/darken/butler/common/files/GatewaySwitch.kt`)
- File operations → Trash bin: deletes to trash
- ADB access → Root / Shizuku: uses privilege
