# yorukot/superfile architecture

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

- Interactive diagram: https://gitdiagram.com/yorukot/superfile
- Repository: https://github.com/yorukot/superfile

## Overview

superfile is a terminal file manager. The main workflow starts in the CLI, loads configuration, launches the Bubble Tea application, and presents file-navigation and preview UI; users can also manage files and inspect metadata. The tree and excerpts support major UI and image-preview components, while README documents themes, hotkeys, and plugins. Some UI and operation wiring is unsampled, so those relationships are omitted rather than inferred; paths for documented but unsampled capabilities use existing enclosing directories.

Main entry points: [`src/internal/model.go`](https://github.com/yorukot/superfile/blob/main/src/internal/model.go) (Application model), [`src/cmd/main.go`](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go) (CLI and startup), [`src/pkg/file_preview/image_preview.go`](https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/image_preview.go) (Image preview engine), [`src/internal/ui/filepanel/update.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/filepanel/update.go) (File panels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_cli["CLI and startup<br/>[main.go]"]
end

subgraph group_state["Application state"]
  node_app["Application model<br/>[model.go]"]
  node_configuration["Configuration and hotkeys<br/>[load_config.go]"]
  node_themes["Themes"]
end

subgraph group_panels["Navigation panels"]
  node_filemodel["File model<br/>[update.go]"]
  node_filepanels["File panels<br/>[update.go]"]
  node_sidebar["Sidebar<br/>[sidebar.go]"]
  node_zoxide["Directory jump<br/>[model.go]"]
end

subgraph group_features["File features"]
  node_preview["File preview panel<br/>[render.go]"]
  node_metadata["File metadata<br/>[model.go]"]
  node_fileops["File operations"]
  node_process["Operation progress<br/>[model.go]"]
  node_clipboard["Clipboard panel<br/>[model.go]"]
  node_help["Help menu<br/>[data.go]"]
  node_plugins["Plugins"]
end

subgraph group_render["Preview and rendering"]
  node_imagepreview["Image preview engine<br/>[image_preview.go]"]
  node_thumbnails["Thumbnail generation"]
  node_cache[("Preview cache<br/>[cache.go]")]
  node_renderer["Terminal rendering<br/>[renderer.go]"]
end

node_user(("Terminal user"))
node_external_terminal(("Terminal"))
node_release_service(("Release service"))

node_user -->|"starts"| node_cli
node_cli -->|"loads"| node_configuration
node_cli -->|"launches"| node_app
node_app -->|"updates"| node_filemodel
node_app -->|"coordinates"| node_filepanels
node_app -->|"updates"| node_sidebar
node_app -->|"updates"| node_preview
node_app -->|"requests"| node_metadata
node_app -->|"dispatches"| node_zoxide
node_filepanels -.->|"renders images"| node_imagepreview
node_imagepreview -->|"reads and writes"| node_cache
node_imagepreview -.->|"generates previews"| node_thumbnails
node_preview -->|"uses rendering"| node_renderer
node_fileops -.->|"reports progress"| node_process
node_app -.->|"renders UI"| node_external_terminal
node_cli -->|"checks releases"| node_release_service

click node_cli "https://github.com/yorukot/superfile/blob/main/src/cmd/main.go"
click node_app "https://github.com/yorukot/superfile/blob/main/src/internal/model.go"
click node_configuration "https://github.com/yorukot/superfile/blob/main/src/internal/common/load_config.go"
click node_filemodel "https://github.com/yorukot/superfile/blob/main/src/internal/ui/filemodel/update.go"
click node_filepanels "https://github.com/yorukot/superfile/blob/main/src/internal/ui/filepanel/update.go"
click node_sidebar "https://github.com/yorukot/superfile/blob/main/src/internal/ui/sidebar/sidebar.go"
click node_zoxide "https://github.com/yorukot/superfile/blob/main/src/internal/ui/zoxide/model.go"
click node_preview "https://github.com/yorukot/superfile/blob/main/src/internal/ui/preview/render.go"
click node_metadata "https://github.com/yorukot/superfile/blob/main/src/internal/ui/metadata/model.go"
click node_fileops "https://github.com/yorukot/superfile/blob/main/src/internal/handle_file_operations.go"
click node_process "https://github.com/yorukot/superfile/blob/main/src/internal/ui/processbar/model.go"
click node_clipboard "https://github.com/yorukot/superfile/blob/main/src/internal/ui/clipboard/model.go"
click node_help "https://github.com/yorukot/superfile/blob/main/src/internal/ui/helpmenu/data.go"
click node_themes "https://github.com/yorukot/superfile/tree/main/src/config"
click node_plugins "https://github.com/yorukot/superfile/tree/main/src/internal"
click node_imagepreview "https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/image_preview.go"
click node_thumbnails "https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/thumbnail_generator.go"
click node_cache "https://github.com/yorukot/superfile/blob/main/src/pkg/cache/cache.go"
click node_renderer "https://github.com/yorukot/superfile/blob/main/src/internal/ui/rendering/renderer.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_user toneBlue
class node_app,node_configuration,node_themes toneAmber
class node_filemodel,node_filepanels,node_sidebar,node_zoxide toneMint
class node_preview,node_metadata,node_fileops,node_process,node_clipboard,node_help,node_plugins toneRose
class node_imagepreview,node_thumbnails,node_cache,node_renderer,node_external_terminal,node_release_service toneIndigo
```

## Components

### Application entry

- [CLI and startup](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go): `src/cmd/main.go`

### Application state

- [Application model](https://github.com/yorukot/superfile/blob/main/src/internal/model.go): `src/internal/model.go`
- [Configuration and hotkeys](https://github.com/yorukot/superfile/blob/main/src/internal/common/load_config.go): `src/internal/common/load_config.go`
- [Themes](https://github.com/yorukot/superfile/tree/main/src/config): `src/config`

### Navigation panels

- [File model](https://github.com/yorukot/superfile/blob/main/src/internal/ui/filemodel/update.go): `src/internal/ui/filemodel/update.go`
- [File panels](https://github.com/yorukot/superfile/blob/main/src/internal/ui/filepanel/update.go): `src/internal/ui/filepanel/update.go`
- [Sidebar](https://github.com/yorukot/superfile/blob/main/src/internal/ui/sidebar/sidebar.go): `src/internal/ui/sidebar/sidebar.go`
- [Directory jump](https://github.com/yorukot/superfile/blob/main/src/internal/ui/zoxide/model.go): `src/internal/ui/zoxide/model.go`

### File features

- [File preview panel](https://github.com/yorukot/superfile/blob/main/src/internal/ui/preview/render.go): `src/internal/ui/preview/render.go`
- [File metadata](https://github.com/yorukot/superfile/blob/main/src/internal/ui/metadata/model.go): `src/internal/ui/metadata/model.go`
- [File operations](https://github.com/yorukot/superfile/blob/main/src/internal/handle_file_operations.go): `src/internal/handle_file_operations.go`
- [Operation progress](https://github.com/yorukot/superfile/blob/main/src/internal/ui/processbar/model.go): `src/internal/ui/processbar/model.go`
- [Clipboard panel](https://github.com/yorukot/superfile/blob/main/src/internal/ui/clipboard/model.go): `src/internal/ui/clipboard/model.go`
- [Help menu](https://github.com/yorukot/superfile/blob/main/src/internal/ui/helpmenu/data.go): `src/internal/ui/helpmenu/data.go`
- [Plugins](https://github.com/yorukot/superfile/tree/main/src/internal): `src/internal`

### Preview and rendering

- [Image preview engine](https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/image_preview.go): `src/pkg/file_preview/image_preview.go`
- [Thumbnail generation](https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/thumbnail_generator.go): `src/pkg/file_preview/thumbnail_generator.go`
- [Preview cache](https://github.com/yorukot/superfile/blob/main/src/pkg/cache/cache.go): `src/pkg/cache/cache.go`
- [Terminal rendering](https://github.com/yorukot/superfile/blob/main/src/internal/ui/rendering/renderer.go): `src/internal/ui/rendering/renderer.go`

### Other components

- **Terminal user**
- **Terminal**
- **Release service**

## Connections

- Terminal user → CLI and startup: starts
- CLI and startup → Configuration and hotkeys: loads (evidence: `src/cmd/main.go`)
- CLI and startup → Application model: launches (evidence: `src/cmd/main.go`)
- Application model → File model: updates (evidence: `src/internal/model.go`)
- Application model → File panels: coordinates (evidence: `src/internal/model.go`)
- Application model → Sidebar: updates (evidence: `src/internal/model.go`)
- Application model → File preview panel: updates (evidence: `src/internal/model.go`)
- Application model → File metadata: requests (evidence: `src/internal/model.go`)
- Application model → Directory jump: dispatches (evidence: `src/internal/model.go`)
- File panels → Image preview engine: renders images
- Image preview engine → Preview cache: reads and writes (evidence: `src/pkg/file_preview/image_preview.go`)
- Image preview engine → Thumbnail generation: generates previews
- File preview panel → Terminal rendering: uses rendering (evidence: `src/internal/ui/preview/render.go`)
- File operations → Operation progress: reports progress
- Application model → Terminal: renders UI
- CLI and startup → Release service: checks releases (evidence: `src/cmd/main.go`)
