# kde/dolphin architecture

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

- Interactive diagram: https://gitdiagram.com/kde/dolphin
- Repository: https://github.com/kde/dolphin

## Overview

#### Purpose and Runtime
Dolphin is KDE’s native desktop file manager: a C++/Qt GUI for browsing local and remote locations, manipulating files, and presenting metadata-rich directory views. It is built with CMake and integrates with KDE Frameworks, especially KIO-backed file/location access, KDE plugin infrastructure, configuration, and desktop services. Core build composition is in `CMakeLists.txt`, `src/CMakeLists.txt`.

#### Application Entry and Shell
`src/main.cpp` starts the standalone application and creates the primary window. `src/dolphinmainwindow.cpp` owns global menus, actions, toolbars, docking/panels, tabs, and view containers; `src/dolphinpart.cpp` exposes Dolphin as an embeddable KDE Part. Desktop launch and component metadata are `src/org.kde.dolphin.desktop` and `src/dolphinpart.json.in`.

#### Navigation, Tabs, and View Lifecycle
A main window hosts tab pages and one or more view containers, supporting tabbed and split navigation. `src/dolphintabwidget.cpp`, `src/dolphintabpage.cpp`, and `src/dolphinviewcontainer.cpp` coordinate active locations and view focus. URL entry/navigation is handled by `src/dolphinurlnavigator.cpp` and `src/dolphinurlnavigatorscontroller.cpp`; location changes ultimately drive a `DolphinView`.

#### File Browsing Data-to-UI Pipeline
`src/views/dolphinview.cpp` is the central directory-view controller: it coordinates loading a URL, selection, actions, drag/drop, and view properties. `src/kitemviews/kfileitemmodel.cpp` models file items and roles, while `src/kitemviews/kitemlistcontroller.cpp` manages interaction/selection and `src/views/dolphinitemlistview.cpp` adapts the generic item-view layer to Dolphin behavior. This boundary separates asynchronous file enumeration/metadata from Qt widget presentation and input handling. Baloo-related roles and directory counting live behind private view-model support in `src/kitemviews/private/kbaloorolesprovider.cpp` and `src/kitemviews/private/kdirectorycontentscounter.cpp`.

#### File Operations and Extensibility
User actions route from window/view actions and context menus into KDE file-operation services rather than a repository-local filesystem backend. `src/dolphincontextmenu.cpp` assembles context actions; `src/views/draganddrophelper.cpp` handles transfer semantics; `src/dolphinnewfilemenu.cpp` creates files/folders. Item-action plugins are independently built/discovered components under `src/itemactions/CMakeLists.txt`, with metadata such as `src/itemactions/hidefileitemaction.json`. Version-control state is asynchronous and plugin-facing through `src/views/versioncontrol/kversioncontrolplugin.cpp` and `src/views/versioncontrol/updateitemstatesthread.cpp`.

#### Search, Panels, and Auxiliary Surfaces
Search UI turns user-entered terms and filter chips into a structured query in `src/search/dolphinquery.cpp`, with controls in `src/search/bar.cpp`; execution is expected to pass through the location/KIO layer rather than an in-tree search engine. Dock panels provide places, folder trees, metadata previews, and an embedded terminal: `src/panels/places/placespanel.cpp`, `src/panels/information/informationpanel.cpp`, `src/panels/terminal/terminalpanel.cpp`. The terminal panel includes a KIOFuse D-Bus interface declaration at `src/panels/terminal/org.kde.KIOFuse.VFS.xml`.

#### Persistence, IPC, and Desktop Integration
Settings use KDE configuration schemas and are applied to views and UI by `src/settings/dolphinsettingsdialog.cpp`, `src/settings/applyviewpropsjob.cpp`, and `src/views/viewproperties.cpp`; migration scripts/updates preserve older settings. D-Bus exposure is defined by `src/dbusinterface.cpp`, and `plasma-dolphin.service.in` supports desktop-service activation. Trash behavior is encapsulated in `src/trash/dolphintrash.cpp`; optional telemetry/user feedback is supplied through `src/userfeedback/dolphinfeedbackprovider.cpp`.

Main entry points: [`src/dolphinmainwindow.cpp`](https://github.com/kde/dolphin/blob/master/src/dolphinmainwindow.cpp) (Dolphin main window), [`src/views/dolphinview.cpp`](https://github.com/kde/dolphin/blob/master/src/views/dolphinview.cpp) (DolphinView), [`src/dolphincontextmenu.cpp`](https://github.com/kde/dolphin/blob/master/src/dolphincontextmenu.cpp) (Context and new-file actions), [`src/kitemviews/kfileitemmodel.cpp`](https://github.com/kde/dolphin/blob/master/src/kitemviews/kfileitemmodel.cpp) (File item model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Application Shell"]
  node_entry["Application entry<br/>Qt executable<br/>[main.cpp]"]
  node_main_window["Dolphin main window<br/>application shell"]
  node_part["Embeddable Dolphin Part<br/>KDE Part<br/>[dolphinpart.cpp]"]
end

subgraph group_navigation["Navigation &amp; Views"]
  node_tab_navigation["Tabs and view containers<br/>navigation lifecycle"]
  node_url_navigation["URL navigator<br/>location input"]
end

subgraph group_pipeline["Directory View Pipeline"]
  node_dolphin_view["DolphinView<br/>directory view controller<br/>[dolphinview.cpp]"]
  node_file_model["File item model<br/>async item model<br/>[kfileitemmodel.cpp]"]
  node_item_interaction["Item interaction controller<br/>selection controller"]
  node_item_list_view["Dolphin item list view<br/>Qt view adapter"]
end

subgraph group_integration["KDE Integration"]
  node_kio{{"KIO location services<br/>KDE Framework service"}}
  node_settings["Settings and view properties<br/>configuration application"]
  node_dbus["D-Bus desktop service<br/>IPC integration<br/>[dbusinterface.cpp]"]
  node_trash["Trash integration<br/>desktop service<br/>[dolphintrash.cpp]"]
end

subgraph group_extensions["Extensions &amp; Surfaces"]
  node_context_actions["Context and new-file actions<br/>action assembly"]
  node_item_action_plugins["Item-action plugins<br/>KDE plugins<br/>[CMakeLists.txt]"]
  node_version_control["Version-control state<br/>async plugin API"]
  node_search["Search query and bar<br/>structured search UI<br/>[dolphinquery.cpp]"]
  node_dock_panels["Dock panels<br/>auxiliary UI<br/>[placespanel.cpp]"]
end

node_build["CMake build composition<br/>[CMakeLists.txt]"]

node_build -->|"builds"| node_entry
node_entry -->|"creates"| node_main_window
node_main_window -.->|"also exposed as"| node_part
node_main_window -->|"hosts"| node_tab_navigation
node_main_window -->|"hosts"| node_url_navigation
node_tab_navigation -->|"manages"| node_dolphin_view
node_url_navigation -->|"navigates"| node_dolphin_view
node_dolphin_view -->|"loads items from"| node_file_model
node_file_model -->|"enumerates via"| node_kio
node_dolphin_view -->|"coordinates"| node_item_interaction
node_item_interaction -->|"drives input on"| node_item_list_view
node_item_list_view -->|"presents"| node_file_model
node_main_window -->|"routes actions to"| node_context_actions
node_context_actions -->|"loads"| node_item_action_plugins
node_context_actions -->|"executes operations through"| node_kio
node_dolphin_view -.->|"requests state from"| node_version_control
node_search -->|"executes through"| node_kio
node_main_window -->|"docks"| node_dock_panels
node_settings -->|"applies properties to"| node_dolphin_view
node_main_window -.->|"exposes"| node_dbus
node_context_actions -.->|"uses"| node_trash

click node_build "https://github.com/kde/dolphin/blob/master/CMakeLists.txt"
click node_entry "https://github.com/kde/dolphin/blob/master/src/main.cpp"
click node_main_window "https://github.com/kde/dolphin/blob/master/src/dolphinmainwindow.cpp"
click node_part "https://github.com/kde/dolphin/blob/master/src/dolphinpart.cpp"
click node_tab_navigation "https://github.com/kde/dolphin/blob/master/src/dolphintabwidget.cpp"
click node_url_navigation "https://github.com/kde/dolphin/blob/master/src/dolphinurlnavigator.cpp"
click node_dolphin_view "https://github.com/kde/dolphin/blob/master/src/views/dolphinview.cpp"
click node_file_model "https://github.com/kde/dolphin/blob/master/src/kitemviews/kfileitemmodel.cpp"
click node_item_interaction "https://github.com/kde/dolphin/blob/master/src/kitemviews/kitemlistcontroller.cpp"
click node_item_list_view "https://github.com/kde/dolphin/blob/master/src/views/dolphinitemlistview.cpp"
click node_context_actions "https://github.com/kde/dolphin/blob/master/src/dolphincontextmenu.cpp"
click node_item_action_plugins "https://github.com/kde/dolphin/blob/master/src/itemactions/CMakeLists.txt"
click node_version_control "https://github.com/kde/dolphin/blob/master/src/views/versioncontrol/kversioncontrolplugin.cpp"
click node_search "https://github.com/kde/dolphin/blob/master/src/search/dolphinquery.cpp"
click node_dock_panels "https://github.com/kde/dolphin/blob/master/src/panels/places/placespanel.cpp"
click node_settings "https://github.com/kde/dolphin/blob/master/src/settings/dolphinsettingsdialog.cpp"
click node_dbus "https://github.com/kde/dolphin/blob/master/src/dbusinterface.cpp"
click node_trash "https://github.com/kde/dolphin/blob/master/src/trash/dolphintrash.cpp"

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_entry,node_main_window,node_part toneBlue
class node_tab_navigation,node_url_navigation toneAmber
class node_dolphin_view,node_file_model,node_item_interaction,node_item_list_view toneMint
class node_kio,node_settings,node_dbus,node_trash toneRose
class node_context_actions,node_item_action_plugins,node_version_control,node_search,node_dock_panels toneIndigo
class node_build toneNeutral
```

## Components

### Application Shell

- [Application entry](https://github.com/kde/dolphin/blob/master/src/main.cpp): Qt executable · `src/main.cpp`
- [Dolphin main window](https://github.com/kde/dolphin/blob/master/src/dolphinmainwindow.cpp): application shell · Owns global actions, tabs, panels, and view containers. · `src/dolphinmainwindow.cpp`
- [Embeddable Dolphin Part](https://github.com/kde/dolphin/blob/master/src/dolphinpart.cpp): KDE Part · `src/dolphinpart.cpp`

### Navigation & Views

- [Tabs and view containers](https://github.com/kde/dolphin/blob/master/src/dolphintabwidget.cpp): navigation lifecycle · Coordinates active locations, split views, and focus. · `src/dolphintabwidget.cpp`
- [URL navigator](https://github.com/kde/dolphin/blob/master/src/dolphinurlnavigator.cpp): location input · `src/dolphinurlnavigator.cpp`

### Directory View Pipeline

- [DolphinView](https://github.com/kde/dolphin/blob/master/src/views/dolphinview.cpp): directory view controller · Coordinates URL loading, actions, selection, and drag/drop. · `src/views/dolphinview.cpp`
- [File item model](https://github.com/kde/dolphin/blob/master/src/kitemviews/kfileitemmodel.cpp): async item model · Provides file items, metadata, and roles. · `src/kitemviews/kfileitemmodel.cpp`
- [Item interaction controller](https://github.com/kde/dolphin/blob/master/src/kitemviews/kitemlistcontroller.cpp): selection controller · `src/kitemviews/kitemlistcontroller.cpp`
- [Dolphin item list view](https://github.com/kde/dolphin/blob/master/src/views/dolphinitemlistview.cpp): Qt view adapter · `src/views/dolphinitemlistview.cpp`

### KDE Integration

- **KIO location services**: KDE Framework service · Provides local and remote access, enumeration, search, and file operations.
- [Settings and view properties](https://github.com/kde/dolphin/blob/master/src/settings/dolphinsettingsdialog.cpp): configuration application · Applies KDE settings to views and UI. · `src/settings/dolphinsettingsdialog.cpp`
- [D-Bus desktop service](https://github.com/kde/dolphin/blob/master/src/dbusinterface.cpp): IPC integration · `src/dbusinterface.cpp`
- [Trash integration](https://github.com/kde/dolphin/blob/master/src/trash/dolphintrash.cpp): desktop service · `src/trash/dolphintrash.cpp`

### Extensions & Surfaces

- [Context and new-file actions](https://github.com/kde/dolphin/blob/master/src/dolphincontextmenu.cpp): action assembly · `src/dolphincontextmenu.cpp`
- [Item-action plugins](https://github.com/kde/dolphin/blob/master/src/itemactions/CMakeLists.txt): KDE plugins · Independently built and discovered context actions. · `src/itemactions/CMakeLists.txt`
- [Version-control state](https://github.com/kde/dolphin/blob/master/src/views/versioncontrol/kversioncontrolplugin.cpp): async plugin API · `src/views/versioncontrol/kversioncontrolplugin.cpp`
- [Search query and bar](https://github.com/kde/dolphin/blob/master/src/search/dolphinquery.cpp): structured search UI · `src/search/dolphinquery.cpp`
- [Dock panels](https://github.com/kde/dolphin/blob/master/src/panels/places/placespanel.cpp): auxiliary UI · Places, information, and terminal surfaces. · `src/panels/places/placespanel.cpp`

### Other components

- [CMake build composition](https://github.com/kde/dolphin/blob/master/CMakeLists.txt): build · `CMakeLists.txt`

## Connections

- CMake build composition → Application entry: builds
- Application entry → Dolphin main window: creates
- Dolphin main window → Embeddable Dolphin Part: also exposed as
- Dolphin main window → Tabs and view containers: hosts
- Dolphin main window → URL navigator: hosts
- Tabs and view containers → DolphinView: manages
- URL navigator → DolphinView: navigates
- DolphinView → File item model: loads items from
- File item model → KIO location services: enumerates via
- DolphinView → Item interaction controller: coordinates
- Item interaction controller → Dolphin item list view: drives input on
- Dolphin item list view → File item model: presents
- Dolphin main window → Context and new-file actions: routes actions to
- Context and new-file actions → Item-action plugins: loads
- Context and new-file actions → KIO location services: executes operations through
- DolphinView → Version-control state: requests state from
- Search query and bar → KIO location services: executes through
- Dolphin main window → Dock panels: docks
- Settings and view properties → DolphinView: applies properties to
- Dolphin main window → D-Bus desktop service: exposes
- Context and new-file actions → Trash integration: uses
