mdgaziur/findex

1. Workspace shape

- This is a Rust workspace with three core crates:

- findex: the actual launcher application.

- findex-daemon: a small helper process for external triggering.

- findex-plugin: the ABI/support crate used by dynamically loaded plugins.

- The rest of the repo is packaging, samples, and deployment glue.

2. Primary runtime: findex

- crates/findex/src/main.rs is the main executable entry point.

- It is a GTK3 desktop app for Linux that opens a launcher window, reads user input, computes results, and executes the chosen target.

- The app is split into smaller UI modules under src/gui/, which keeps the launcher shell, search input, result list, and dialog behavior separate.

3. UI composition

- The launcher UI is built from a small set of GTK widgets:

- search box (searchbox.rs)

- scrollable results list (result_list.rs, result_list_row.rs)

- dialog/window chrome (dialog.rs)

- The README’s CSS class table matches these widget boundaries, so styling is a first-class part of the UI architecture rather than an afterthought.

4. Search and result data flow

- User input flows from the search box into the launcher logic.

- Results are assembled from multiple sources:

- local application entries via app_list.rs

- plugin-provided results via the plugin subsystem

- The result list is then rendered in the GTK list view, and selection/keyboard shortcuts are used to launch the chosen result.

5. Application discovery

- app_list.rs suggests the launcher maintains a catalog of installed desktop applications, likely from standard Linux application metadata.

- This forms the built-in search corpus, separate from plugin results.

- The app list is one of the main data sources feeding the ranking/filtering path.

6. Configuration and theming boundary

- config.rs handles runtime behavior settings, loaded from user config.

- Behavior is driven by ~/.config/findex/settings.toml, while visuals come from style.css.

- The repo also includes a bundled default stylesheet under css/style.css, which is copied into the install location and can be overridden by the user.

7. Activation and daemon boundary

- findex-daemon is a separate process whose role is to make the launcher triggerable externally, especially in environments where global hotkeys are limited.

- The README shows a toggle_file-based control path under ~/.config/findex/, so the daemon acts as a bridge between external events and the GUI launcher.

- On X11 the app can bind keys directly; on Wayland the daemon/file-trigger path becomes the workaround.

8. Plugin architecture

- findex-plugin defines the stable plugin interface and result types used across dynamic library boundaries.

- It uses an ABI-stability layer (abi_stable) so plugins can be compiled separately and loaded as .so files.

- The plugin contract is simple: initialize with config, then handle a query and return a list of results.

9. Plugin ecosystem

- The plugins/ directory contains example plugins such as cmd, github-repo, math, and urlopen.

- These are separate crates, built as shared libraries, and illustrate how the launcher is extended without changing the main binary.

- Plugins can be invoked by prefix and optionally by custom keyboard shortcut, which inserts the prefix into the search box.

10. Packaging and deployment

- installer.sh, service/findex-daemon.service, and the README’s installation notes show that deployment is part of the repo’s architecture.

- The daemon is intended to run as a user service or autostart process.

- Logs are written to ${XDG_CACHE_HOME}/findex-logs, which is the main operational boundary for debugging.

11. Net effect

- The architecture is: GTK launcher UI at the center, local app search as the default corpus, plugins as extensible result providers, and a small daemon as the external trigger path.

- Styling and behavior are both user-configurable through files, while the plugin interface is isolated behind a dedicated ABI crate.