| name | app-guide |
| description | Application overview for frename. Use when: orienting to the project for the first time, deciding which crate or module to touch, understanding what the app does end-to-end, looking up where a concept lives (tags, files, ordering, colors), or understanding keyboard shortcuts and the tag/file lifecycle.
|
| disable-model-invocation | false |
Application Overview — frename
WHEN to use this skill
- Orienting to the project for the first time
- Deciding which crate or module to touch for a given change
- Understanding what the app does end-to-end
- Looking up where a concept lives (tags, files, ordering, colors, sessions)
- Understanding keyboard shortcuts or the tag/file lifecycle
What the app does
frename is a Windows desktop app for renaming video and image files using a tag-based system.
File name format: tag1.tag2.name.ext
The user opens a folder, browses video files, assigns tags by clicking checkboxes, optionally reorders tags by dragging chips in the rename panel, and the file is renamed when they move to the next file.
Cargo workspace
C:\Work\my\frename\
Cargo.toml workspace manifest
crates\frename-core\ library: pure business logic (no iced)
src\ binary: UI (iced 0.14, gstreamer video)
frename-core dependencies
rusqlite (SQLite, bundled), tokio (async file scan), uuid, indexmap, log
frename (binary) dependencies
iced 0.14, iced_video_player (GStreamer), frename-core
Source map
frename-core (crates/frename-core/src/)
| Path | What lives here |
|---|
lib.rs | All public exports |
db/traits.rs | AppStateStore, StoredTagStore, Initializable traits |
db/app_database.rs | AppDatabase — SQLite implementation |
db/fake_app_storage.rs | FakeAppStorage — in-memory test double |
db/migrations.rs | Schema creation (3 tables) |
ordered/collection.rs | OrderedCollection<K,V> — ordered dict with rebalance |
tags/tag_list.rs | TagList<S> — all tag state and operations |
tags/tag.rs | Tag, TagId structs |
tags/file_snapshot.rs | FileSnapshot — checked tags + name + ext |
tags/file_tagger.rs | FileTagger::parse, SaveAndReparse — file name ↔ snapshot |
tags/stored_tag.rs | StoredTag, TagColorMapping |
file.rs | File — path + metadata + snapshot |
directory.rs | Directory<S> — folder with sorted file list + selection |
folder_file.rs | FolderAndFile — session: folder path + optional file path |
frename binary (src/)
| Path | What lives here |
|---|
main.rs | Logging init, GStreamer check, iced::application |
app/ | FrenameApp root: routes messages, global subscription |
features/folder_workspace/ | Main coordinator: directory, file workspace, layout |
features/file_workspace/ | Current file + TagList + tag operations |
features/tag_panel/ | Tag selection grid: cursor, bounds, scroll state |
features/tag_grid/ | Tag grid view (used when panel is wide enough) |
features/file_name_panel/ | Rename chips panel: drag, trash zone, name line |
features/folder/ | File list panel: selection messages |
features/folder_controls/ | Folder navigation controls |
features/video_player/ | GStreamer video playback state |
features/video_controls/ | Progress bar, play/pause |
features/drag_drop/ | OS file drag-drop → OpenFile(path) |
widgets/ | 5 reusable widgets (search_bar, tag_chip, splitter, etc.) |
theme.rs | Color constants + style functions |
tag_colors.rs | 16-color tag palette |
Key concepts
Tags
- Stored tag: persisted in DB with a UUID, sort_order, and color (by tag name)
- Snapshot-only tag: exists in the current file name but not in DB; shown as unsaved (○ button to save)
- Checked tag: applied to the current file; appears in the rename panel as a chip
- Unchecked tag: in the tag panel but not applied to this file
Tag ordering (two independent orders)
display_tag_ids — display order in the tag panel; set at file-open, never reordered; used for persistenceselected_tag_ids — order of chips in the file name panel; reorderable via drag; determines file name tag order
File lifecycle
ScanFolder → async scan → FolderLoaded → FileOpened → user edits tags → switch file → FileUpdated (disk rename)
Tags are never written to disk while editing. The rename happens only when the user moves to another file (or the app closes). Video must unload before rename on Windows (GStreamer holds a file handle).
Session persistence
Last opened folder + file stored in folder_history SQLite table. Restored on startup via LoadLastSession.
Keyboard shortcuts
| Key | Action |
|---|
Space | Toggle the selected tag (strips trailing space from filter first) |
Escape | Clear the search filter |
← / → / ↑ / ↓ | Move tag grid cursor (wraps at edges) |
PageUp / PageDown | Previous / next file |
Delete | Remove the selected tag from DB and UI |
Enter | Save the selected unsaved tag to DB |
| Any char / Backspace | Focus search bar and emulate the key into the filter |
Tag colors
tag_colors::TagColors::PALETTE — 16 fixed colors (grays, blues, greens, ambers, etc.).
TagColors::color(index: u8) -> Color — wraps index modulo 16.
Color is assigned randomly when a tag is saved for the first time (random_color_index() in core).
Colors are stored by tag name in tag_color_mapping table, so they survive renames if done via save_tag.
Startup sequence
main() → init logging + check GStreamer
iced::application(FrenameApp::new)
→ FrenameApp::new() → FolderWorkspace::new()
→ WindowReady event → LoadLastSession
→ LoadLastSession → AppStateStore::get_last_session() → ScanFolder(session)
→ ScanFolder → async Directory::open() → FolderLoaded { directory, target_file }
→ FolderLoaded → select target file → FileOpened(file)
→ FileOpened → FileWorkspace::set_file(file) → TagList::new(store, snapshot)
→ video_player.load_video(path)
Common patterns
Open a folder/file from outside: emit Message::FolderWorkspace(OpenFile(path)) or drop a file on the window (handled by drag_drop feature).
The LoggingAppStateStore<AppDatabase> wrapper: used in production to log all store operations. Passed to Directory::open(). The underlying AppDatabase is used directly in FileWorkspace.
Generic type resolution: FolderWorkspace uses type Directory = frename_core::Directory<LoggingAppStateStore<AppDatabase>>. All generics are pinned at this level; the rest of the UI is concrete.
