# lambchwrlie95/omarchy-circle-search architecture

> Architecture diagram of the GitHub repository lambchwrlie95/omarchy-circle-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lambchwrlie95/omarchy-circle-search
- Repository: https://github.com/lambchwrlie95/omarchy-circle-search

## Overview

1. **Purpose and runtime model**
   - `omarchy-circle-search` is a small Rust/GTK4 Wayland utility, not a background daemon.
   - It launches on demand, shows a full-screen overlay, lets the user draw a freehand selection, then either uploads the crop for reverse-image search or copies it for AI-chat use.

2. **Top-level orchestration**
   - `src/main.rs` is the entrypoint and control plane.
   - It handles CLI flags like `--copy` and `--notify`, performs dependency checks, loads config/theme, starts the overlay, and dispatches the result into the correct post-capture flow.

3. **Overlay and input capture boundary**
   - `src/overlay.rs` owns the interactive UI.
   - It uses GTK4 with `gtk4-layer-shell` to present a Wayland-native overlay above the desktop.
   - This layer handles engine selection, mouse drag tracking, keyboard shortcuts, escape-to-cancel, and the “shake” feedback for tiny invalid selections.

4. **Screen capture subsystem**
   - `src/capture.rs` wraps `grim` for screenshots.
   - The design is optimized for perceived speed: it grabs the background screenshot before the GTK UI is fully up, then later produces the final cropped image from the user’s selection geometry.

5. **Search and post-processing subsystem**
   - `src/search.rs` is the outbound integration layer.
   - It branches into two distinct behaviors:
     - **Image-search mode:** upload PNG data to an image host, then open the selected search engine URL in the browser.
     - **AI-chat mode:** copy the captured PNG to the clipboard and open the configured chat URL, optionally auto-pasting with `wtype`.

6. **External service dependency**
   - Reverse-image engines do not receive the image directly from the app; they need a reachable URL.
   - The app therefore uploads to Imgur first, with a fallback to `0x0.st` if that fails.
   - AI chat mode intentionally skips upload and stays local until the browser handoff.

7. **Configuration boundary**
   - `src/config.rs` reads and writes `~/.config/omarchy/circle-search.toml`.
   - Configuration controls which engine pills appear, their order, and AI-chat/upload settings.
   - The config format is permissive: unknown keys are ignored so the file can evolve without breaking older versions.

8. **Theme integration**
   - `src/theme.rs` reads Omarchy theme colors from `~/.config/omarchy/current/theme/colors.toml`.
   - This makes the overlay feel like part of the desktop rather than a standalone utility.
   - Theming is a read-only dependency from the user’s existing Omarchy installation.

9. **User feedback and notifications**
   - `omarchy-notification-send` is used for success/error feedback and optional completion notices.
   - This is part of the app’s integration with Omarchy conventions rather than a generic desktop notification stack.

10. **Clipboard, browser, and shell-tool dependencies**
   - The app relies on external command-line tools for key system interactions:
     - `wl-copy` for clipboard writes
     - `xdg-open` for opening search/chat URLs
     - `curl` and `python3` for upload/helper flows
     - `wtype` for optional AI-chat paste/submit automation
   - These tools are a key architectural boundary: Rust owns orchestration, but the actual desktop actions are delegated to established Unix utilities.

11. **Main end-to-end data flow**
   - Startup: CLI/config/theme/dependency checks.
   - UI: capture background screenshot, display overlay, collect selection and engine choice.
   - Execution:
     - crop region from screenshot
     - either upload and open a search URL, or copy to clipboard and open chat
   - Feedback: notify the user and exit.

12. **Repository shape**
   - The codebase is intentionally small and split by responsibility:
     - `main.rs` = orchestration
     - `overlay.rs` = UI/input
     - `capture.rs` = screenshot/cropping
     - `search.rs` = external search/chat integration
     - `theme.rs` = Omarchy styling
     - `config.rs` = persistent user settings
   - That separation maps cleanly to the architecture diagram: one interactive front-end, one capture pipeline, and one outbound integration layer.

Main entry points: [`src/main.rs`](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/main.rs) (main), [`src/search.rs`](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/search.rs) (search), [`src/overlay.rs`](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/overlay.rs) (overlay), [`src/capture.rs`](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/capture.rs) (capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_orchestration["Orchestration"]
  node_main["main<br/>entrypoint<br/>[main.rs]"]
end

subgraph group_grp_interactive["Interactive UI"]
  node_overlay["overlay<br/>[overlay.rs]"]
end

subgraph group_grp_pipelines["Capture & Outbound"]
  node_capture["capture<br/>screenshot pipeline<br/>[capture.rs]"]
  node_search["search<br/>post-action<br/>[search.rs]"]
end

subgraph group_grp_state["State & Styling"]
  node_config["config<br/>settings<br/>[config.rs]"]
  node_theme["theme<br/>styling<br/>[theme.rs]"]
end

subgraph group_grp_external["External Tools"]
  node_gtk_layer_shell{{"layer shell<br/>wayland UI lib"}}
  node_grim{{"grim<br/>screenshot tool"}}
  node_imgur[("Imgur<br/>image host")]
  node_ox0[("0x0.st<br/>fallback upload")]
  node_wlcopy{{"wl-copy<br/>clipboard tool"}}
  node_xdgopen{{"xdg-open<br/>launcher"}}
  node_wtype{{"wtype<br/>input tool"}}
  node_notify{{"notify<br/>notification tool"}}
end

node_main -->|"load/save"| node_config
node_main -->|"load"| node_theme
node_main -->|"start UI"| node_overlay
node_main -->|"prepare capture"| node_capture
node_main -->|"dispatch result"| node_search
node_overlay -->|"present"| node_gtk_layer_shell
node_overlay -->|"request screenshot"| node_capture
node_capture -->|"backend"| node_grim
node_search -->|"upload"| node_imgur
node_search -.->|"fallback"| node_ox0
node_search -->|"copy png"| node_wlcopy
node_search -->|"open url"| node_xdgopen
node_search -.->|"auto paste"| node_wtype
node_main -->|"feedback"| node_notify
node_overlay -->|"selection result"| node_main

click node_main "https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/main.rs"
click node_overlay "https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/overlay.rs"
click node_capture "https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/capture.rs"
click node_search "https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/search.rs"
click node_config "https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/config.rs"
click node_theme "https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/theme.rs"

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_main toneBlue
class node_overlay toneAmber
class node_capture,node_search toneMint
class node_config,node_theme toneRose
class node_gtk_layer_shell,node_grim,node_imgur,node_ox0,node_wlcopy,node_xdgopen,node_wtype,node_notify toneIndigo
```

## Components

### Orchestration

Startup, control flow, and app-wide coordination

- [main](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/main.rs): entrypoint · CLI entrypoint and control plane · `src/main.rs`

### Interactive UI

Overlay and input handling

- [overlay](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/overlay.rs): gtk overlay · Full-screen Wayland overlay and selection UI · `src/overlay.rs`

### Capture & Outbound

Screenshot capture and post-selection actions

- [capture](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/capture.rs): screenshot pipeline · Background grab and final crop generation · `src/capture.rs`
- [search](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/search.rs): post-action · Upload, open browser, or copy-to-chat flow · `src/search.rs`

### State & Styling

Persistent config and desktop theming

- [config](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/config.rs): settings · Reads and writes user preferences · `src/config.rs`
- [theme](https://github.com/lambchwrlie95/omarchy-circle-search/blob/main/src/theme.rs): styling · Loads Omarchy theme colors · `src/theme.rs`

### External Tools

Desktop utilities and remote services the app delegates to

- **layer shell**: wayland UI lib · Positions the overlay above the desktop
- **grim**: screenshot tool · External screenshot backend
- **Imgur**: image host · Primary upload target for reverse-image search
- **0x0.st**: fallback upload · Backup upload target if primary upload fails
- **wl-copy**: clipboard tool · Writes PNG data to the clipboard
- **xdg-open**: launcher · Opens search and chat URLs in the browser
- **wtype**: input tool · Optional automated paste and submit
- **notify**: notification tool · Success, error, and completion feedback

## Connections

- main → config: load/save · Reads user settings and persists updates
- main → theme: load · Loads desktop theme colors before UI startup
- main → overlay: start UI · Launches the full-screen selection overlay
- main → capture: prepare capture · Initializes screenshot capture for the session
- main → search: dispatch result · Routes the selected crop into image-search or AI-chat flow
- overlay → layer shell: present · Uses Wayland layer-shell for desktop overlay placement
- overlay → capture: request screenshot · Consumes the pre-captured background and selection geometry
- capture → grim: backend · Delegates screenshot capture to grim
- search → Imgur: upload · Primary image upload for reverse-image search
- search → 0x0.st: fallback · Uses backup host if primary upload fails
- search → wl-copy: copy png · Copies cropped image for AI-chat mode
- search → xdg-open: open url · Hands off to browser for search or chat
- search → wtype: auto paste · Optionally pastes and submits in chat mode
- main → notify: feedback · Emits success, error, and optional completion notices
- overlay → main: selection result · Returns chosen engine and capture geometry
