# writronic/wherever architecture

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

- Interactive diagram: https://gitdiagram.com/writronic/wherever
- Repository: https://github.com/writronic/wherever

## Overview

Wherever is a macOS file-search app with a Rust indexing and search engine. The main workflow is to enter a query in the app, pass it through a search session to the engine, search indexed file metadata, and display ranked results; users can also search document contents and inspect or edit archives. The graph includes the documented launcher, CLI, live updates, and volume selection. Some UI-to-service wiring and unsampled feature internals are not shown, so those relationships are omitted or marked unverified.

Main entry points: [`Engine/wherever-core/src/engine.rs`](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/engine.rs) (Search Engine), [`WhereverKit/SearchService.swift`](https://github.com/writronic/wherever/blob/main/WhereverKit/SearchService.swift) (Search Service), [`Wherever/Views/Search/SearchModel.swift`](https://github.com/writronic/wherever/blob/main/Wherever/Views/Search/SearchModel.swift) (Search State), [`Wherever/Views/Launcher/LauncherPanel.swift`](https://github.com/writronic/wherever/blob/main/Wherever/Views/Launcher/LauncherPanel.swift) (Launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["macOS App"]
  node_appui["Search Interface<br/>[SearchView.swift]"]
  node_searchmodel["Search State<br/>[SearchModel.swift]"]
  node_filters["Search Filters"]
  node_results["Results and Inspector<br/>[ResultsTable.swift]"]
  node_launcher["Launcher"]
  node_locations["Disk Selection"]
end

subgraph group_bridge["Service Bridge"]
  node_services["App Services"]
  node_searchservice["Search Service"]
  node_events["Event Adapter<br/>[EngineEvents.swift]"]
  node_interface["Search API<br/>[Search.swift]"]
end

subgraph group_engine["Search Engine"]
  node_engine["Search Engine<br/>[engine.rs]"]
  node_crawler["Filesystem Crawl<br/>[crawl.rs]"]
  node_index[("Persistent Index<br/>[index.rs]")]
  node_query["Query Matching<br/>[query.rs]"]
  node_ranking["Result Ranking<br/>[rank.rs]"]
  node_live["Live Index Updates<br/>[live.rs]"]
  node_watcher["Filesystem Events<br/>[fsevents.rs]"]
end

subgraph group_content["Content and Archives"]
  node_contentsearch["Document Text Search<br/>[search.rs]"]
  node_archive["Archive Operations<br/>[archive.rs]"]
end

subgraph group_entry["Other Entry Points"]
  node_cli["Command-Line Search<br/>[main.rs]"]
  node_helper["Menu Bar Helper<br/>[HelperApp.swift]"]
end

node_user(("Mac User"))

node_user -->|"enters query"| node_appui
node_appui -->|"updates state"| node_searchmodel
node_searchmodel -->|"uses filters"| node_filters
node_results -.->|"shows results"| node_searchmodel
node_launcher -.->|"searches names"| node_searchmodel
node_searchmodel -.->|"requests searches"| node_searchservice
node_services -->|"creates service"| node_searchservice
node_searchservice -->|"calls engine"| node_engine
node_searchservice -->|"implements client"| node_interface
node_searchservice -->|"forwards events"| node_events
node_locations -.->|"selects volumes"| node_searchservice
node_engine -->|"crawls files"| node_crawler
node_engine -->|"builds index"| node_index
node_engine -->|"runs matching"| node_query
node_engine -->|"ranks matches"| node_ranking
node_engine -->|"updates index"| node_live
node_engine -->|"configures watching"| node_watcher
node_engine -->|"searches contents"| node_contentsearch
node_engine -->|"handles archives"| node_archive
node_user -->|"searches terminal"| node_cli
node_user -->|"opens shortcut"| node_launcher
node_helper -.->|"opens launcher"| node_launcher
node_user -->|"searches document text"| node_contentsearch
node_user -->|"inspects archives"| node_archive
node_user -->|"chooses disks"| node_locations

click node_appui "https://github.com/writronic/wherever/blob/main/Wherever/Views/Search/SearchView.swift"
click node_searchmodel "https://github.com/writronic/wherever/blob/main/Wherever/Views/Search/SearchModel.swift"
click node_filters "https://github.com/writronic/wherever/blob/main/Wherever/Views/Filter/SearchFilters.swift"
click node_results "https://github.com/writronic/wherever/blob/main/Wherever/Views/Results/ResultsTable.swift"
click node_launcher "https://github.com/writronic/wherever/blob/main/Wherever/Views/Launcher/LauncherPanel.swift"
click node_locations "https://github.com/writronic/wherever/blob/main/Wherever/Views/Settings/LocationsModel.swift"
click node_services "https://github.com/writronic/wherever/blob/main/WhereverKit/WhereverServices.swift"
click node_searchservice "https://github.com/writronic/wherever/blob/main/WhereverKit/SearchService.swift"
click node_events "https://github.com/writronic/wherever/blob/main/WhereverKit/EngineEvents.swift"
click node_interface "https://github.com/writronic/wherever/blob/main/Packages/WhereverInterface/Sources/WhereverInterface/Search.swift"
click node_engine "https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/engine.rs"
click node_crawler "https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/crawl.rs"
click node_index "https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/index.rs"
click node_query "https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/query.rs"
click node_ranking "https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/rank.rs"
click node_live "https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/live.rs"
click node_watcher "https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/fsevents.rs"
click node_contentsearch "https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/text/search.rs"
click node_archive "https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/archive.rs"
click node_cli "https://github.com/writronic/wherever/blob/main/Engine/wherever-cli/src/main.rs"
click node_helper "https://github.com/writronic/wherever/blob/main/WhereverHelper/HelperApp.swift"

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_appui,node_searchmodel,node_filters,node_results,node_launcher,node_locations,node_user toneBlue
class node_services,node_searchservice,node_events,node_interface toneAmber
class node_engine,node_crawler,node_index,node_query,node_ranking,node_live,node_watcher toneMint
class node_contentsearch,node_archive toneRose
class node_cli,node_helper toneIndigo
```

## Components

### macOS App

- [Search Interface](https://github.com/writronic/wherever/blob/main/Wherever/Views/Search/SearchView.swift): `Wherever/Views/Search/SearchView.swift`
- [Search State](https://github.com/writronic/wherever/blob/main/Wherever/Views/Search/SearchModel.swift): `Wherever/Views/Search/SearchModel.swift`
- [Search Filters](https://github.com/writronic/wherever/blob/main/Wherever/Views/Filter/SearchFilters.swift): `Wherever/Views/Filter/SearchFilters.swift`
- [Results and Inspector](https://github.com/writronic/wherever/blob/main/Wherever/Views/Results/ResultsTable.swift): `Wherever/Views/Results/ResultsTable.swift`
- [Launcher](https://github.com/writronic/wherever/blob/main/Wherever/Views/Launcher/LauncherPanel.swift): `Wherever/Views/Launcher/LauncherPanel.swift`
- [Disk Selection](https://github.com/writronic/wherever/blob/main/Wherever/Views/Settings/LocationsModel.swift): `Wherever/Views/Settings/LocationsModel.swift`

### Service Bridge

- [App Services](https://github.com/writronic/wherever/blob/main/WhereverKit/WhereverServices.swift): `WhereverKit/WhereverServices.swift`
- [Search Service](https://github.com/writronic/wherever/blob/main/WhereverKit/SearchService.swift): `WhereverKit/SearchService.swift`
- [Event Adapter](https://github.com/writronic/wherever/blob/main/WhereverKit/EngineEvents.swift): `WhereverKit/EngineEvents.swift`
- [Search API](https://github.com/writronic/wherever/blob/main/Packages/WhereverInterface/Sources/WhereverInterface/Search.swift): `Packages/WhereverInterface/Sources/WhereverInterface/Search.swift`

### Search Engine

- [Search Engine](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/engine.rs): `Engine/wherever-core/src/engine.rs`
- [Filesystem Crawl](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/crawl.rs): `Engine/wherever-core/src/crawl.rs`
- [Persistent Index](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/index.rs): `Engine/wherever-core/src/index.rs`
- [Query Matching](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/query.rs): `Engine/wherever-core/src/query.rs`
- [Result Ranking](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/rank.rs): `Engine/wherever-core/src/rank.rs`
- [Live Index Updates](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/live.rs): `Engine/wherever-core/src/live.rs`
- [Filesystem Events](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/fsevents.rs): `Engine/wherever-core/src/fsevents.rs`

### Content and Archives

- [Document Text Search](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/text/search.rs): `Engine/wherever-core/src/text/search.rs`
- [Archive Operations](https://github.com/writronic/wherever/blob/main/Engine/wherever-core/src/archive.rs): `Engine/wherever-core/src/archive.rs`

### Other Entry Points

- [Command-Line Search](https://github.com/writronic/wherever/blob/main/Engine/wherever-cli/src/main.rs): `Engine/wherever-cli/src/main.rs`
- [Menu Bar Helper](https://github.com/writronic/wherever/blob/main/WhereverHelper/HelperApp.swift): `WhereverHelper/HelperApp.swift`

### Other components

- **Mac User**

## Connections

- Mac User → Search Interface: enters query (evidence: `README.md`)
- Search Interface → Search State: updates state (evidence: `Wherever/ContentView.swift`)
- Search State → Search Filters: uses filters (evidence: `Wherever/Views/Search/SearchModel.swift`)
- Results and Inspector → Search State: shows results
- Launcher → Search State: searches names
- Search State → Search Service: requests searches
- App Services → Search Service: creates service (evidence: `WhereverKit/WhereverServices.swift`)
- Search Service → Search Engine: calls engine (evidence: `WhereverKit/SearchService.swift`)
- Search Service → Search API: implements client (evidence: `WhereverKit/SearchService.swift`)
- Search Service → Event Adapter: forwards events (evidence: `WhereverKit/SearchService.swift`)
- Disk Selection → Search Service: selects volumes
- Search Engine → Filesystem Crawl: crawls files (evidence: `Engine/wherever-core/src/engine.rs`)
- Search Engine → Persistent Index: builds index (evidence: `Engine/wherever-core/src/engine.rs`)
- Search Engine → Query Matching: runs matching (evidence: `Engine/wherever-core/src/engine.rs`)
- Search Engine → Result Ranking: ranks matches (evidence: `Engine/wherever-core/src/engine.rs`)
- Search Engine → Live Index Updates: updates index (evidence: `Engine/wherever-core/src/engine.rs`)
- Search Engine → Filesystem Events: configures watching (evidence: `Engine/wherever-core/src/engine.rs`)
- Search Engine → Document Text Search: searches contents (evidence: `Engine/wherever-core/src/engine.rs`)
- Search Engine → Archive Operations: handles archives (evidence: `Engine/wherever-core/src/engine.rs`)
- Mac User → Command-Line Search: searches terminal (evidence: `README.md`)
- Mac User → Launcher: opens shortcut (evidence: `README.md`)
- Menu Bar Helper → Launcher: opens launcher
- Mac User → Document Text Search: searches document text (evidence: `README.md`)
- Mac User → Archive Operations: inspects archives (evidence: `README.md`)
- Mac User → Disk Selection: chooses disks (evidence: `README.md`)