# wwwoper/notesearch architecture

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

- Interactive diagram: https://gitdiagram.com/wwwoper/notesearch
- Repository: https://github.com/wwwoper/notesearch

## Overview

NoteSearch is a native macOS desktop app for searching text in one user-selected folder. The main workflow is global hotkey → search query → ranked file results → highlighted preview → open or reveal the file. Indexing reconciles files at launch and watches for changes; settings configure the folder, exclusions, hotkey, and app behavior. The graph includes the visible UI, state, search, and indexing layers. Some service internals and view behavior were not fully sampled, so those links rely on README statements where available.

Main entry points: [`NoteSearch/Models/AppState.swift`](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Models/AppState.swift) (App state), [`NoteSearch/NoteSearchApp.swift`](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/NoteSearchApp.swift) (App and panel), [`NoteSearch/Services/SearchService.swift`](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/SearchService.swift) (Query and snippets), [`NoteSearch/Services/IndexService.swift`](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/IndexService.swift) (Index service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["App interaction"]
  node_app["App and panel"]
  node_state["App state<br/>[AppState.swift]"]
  node_content["Search window<br/>[ContentView.swift]"]
  node_searchbar["Search bar"]
  node_results["Results list"]
end

subgraph group_search["Search and preview"]
  node_preview["Result preview<br/>[PreviewView.swift]"]
  node_models["Search models<br/>[SearchModels.swift]"]
  node_searchsvc["Query and snippets"]
end

subgraph group_indexing["Index and storage"]
  node_indexsvc["Index service<br/>[IndexService.swift]"]
  node_watcher["File change watcher<br/>[IndexService.swift]"]
  node_disk["Selected folder"]
  node_db[("SQLite FTS index")]
end

subgraph group_configuration["Settings and system"]
  node_hotkey["Global hotkey"]
  node_settings["Settings UI<br/>[SettingsView.swift]"]
  node_log["App logging<br/>[AppLog.swift]"]
end

node_user(("User"))
node_macos["macOS services"]

node_user -->|"presses"| node_hotkey
node_hotkey -->|"triggers panel"| node_app
node_app -->|"hosts"| node_content
node_app -->|"opens"| node_settings
node_user -->|"enters query"| node_searchbar
node_searchbar -->|"updates query"| node_state
node_content -->|"displays"| node_searchbar
node_content -->|"displays"| node_results
node_content -->|"displays"| node_preview
node_state -->|"runs search"| node_searchsvc
node_state -->|"reconciles and reindexes"| node_indexsvc
node_results -->|"reads results"| node_state
node_preview -->|"reads selection"| node_state
node_preview -->|"builds snippets"| node_searchsvc
node_searchsvc -.->|"produces results"| node_models
node_indexsvc -->|"scans and reads"| node_disk
node_watcher -->|"watches changes"| node_disk
node_state -->|"applies changes"| node_watcher
node_indexsvc -->|"writes index"| node_db
node_searchsvc -->|"queries FTS"| node_db
node_settings -->|"changes settings"| node_state
node_settings -->|"configures index"| node_indexsvc
node_settings -->|"configures shortcut"| node_hotkey
node_app -->|"starts handler"| node_hotkey
node_app -.->|"opens files and menus"| node_macos
node_searchsvc -.->|"logs search"| node_log
node_indexsvc -->|"logs indexing"| node_log

click node_hotkey "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/GlobalHotkeyHandler.swift"
click node_app "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/NoteSearchApp.swift"
click node_state "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Models/AppState.swift"
click node_content "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/ContentView.swift"
click node_searchbar "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/SearchBarView.swift"
click node_results "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/ResultsListView.swift"
click node_preview "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/PreviewView.swift"
click node_models "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Models/SearchModels.swift"
click node_searchsvc "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/SearchService.swift"
click node_indexsvc "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/IndexService.swift"
click node_watcher "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/IndexService.swift"
click node_settings "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/SettingsView.swift"
click node_log "https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/AppLog.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_app,node_state,node_content,node_searchbar,node_results,node_user toneBlue
class node_preview,node_models,node_searchsvc toneAmber
class node_indexsvc,node_watcher,node_disk,node_db toneMint
class node_hotkey,node_settings,node_log toneRose
class node_macos toneIndigo
```

## Components

### App interaction

- [App and panel](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/NoteSearchApp.swift): `NoteSearch/NoteSearchApp.swift`
- [App state](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Models/AppState.swift): `NoteSearch/Models/AppState.swift`
- [Search window](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/ContentView.swift): `NoteSearch/Views/ContentView.swift`
- [Search bar](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/SearchBarView.swift): `NoteSearch/Views/SearchBarView.swift`
- [Results list](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/ResultsListView.swift): `NoteSearch/Views/ResultsListView.swift`

### Search and preview

- [Result preview](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/PreviewView.swift): `NoteSearch/Views/PreviewView.swift`
- [Search models](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Models/SearchModels.swift): `NoteSearch/Models/SearchModels.swift`
- [Query and snippets](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/SearchService.swift): `NoteSearch/Services/SearchService.swift`

### Index and storage

- [Index service](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/IndexService.swift): `NoteSearch/Services/IndexService.swift`
- [File change watcher](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/IndexService.swift): `NoteSearch/Services/IndexService.swift`
- **Selected folder**
- **SQLite FTS index**

### Settings and system

- [Global hotkey](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/GlobalHotkeyHandler.swift): `NoteSearch/Services/GlobalHotkeyHandler.swift`
- [Settings UI](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Views/SettingsView.swift): `NoteSearch/Views/SettingsView.swift`
- [App logging](https://github.com/wwwoper/notesearch/blob/main/NoteSearch/Services/AppLog.swift): `NoteSearch/Services/AppLog.swift`

### Other components

- **User**
- **macOS services**

## Connections

- User → Global hotkey: presses (evidence: `README.md`)
- Global hotkey → App and panel: triggers panel (evidence: `NoteSearch/NoteSearchApp.swift`)
- App and panel → Search window: hosts (evidence: `NoteSearch/NoteSearchApp.swift`)
- App and panel → Settings UI: opens (evidence: `NoteSearch/NoteSearchApp.swift`)
- User → Search bar: enters query (evidence: `README.md`)
- Search bar → App state: updates query (evidence: `NoteSearch/Views/SearchBarView.swift`)
- Search window → Search bar: displays (evidence: `NoteSearch/Views/ContentView.swift`)
- Search window → Results list: displays (evidence: `NoteSearch/Views/ContentView.swift`)
- Search window → Result preview: displays (evidence: `NoteSearch/Views/ContentView.swift`)
- App state → Query and snippets: runs search (evidence: `NoteSearch/Models/AppState.swift`)
- App state → Index service: reconciles and reindexes (evidence: `NoteSearch/Models/AppState.swift`)
- Results list → App state: reads results (evidence: `NoteSearch/Views/ResultsListView.swift`)
- Result preview → App state: reads selection (evidence: `NoteSearch/Views/PreviewView.swift`)
- Result preview → Query and snippets: builds snippets (evidence: `NoteSearch/Views/PreviewView.swift`)
- Query and snippets → Search models: produces results
- Index service → Selected folder: scans and reads (evidence: `README.md`)
- File change watcher → Selected folder: watches changes (evidence: `NoteSearch/Services/IndexService.swift`)
- App state → File change watcher: applies changes (evidence: `NoteSearch/Models/AppState.swift`)
- Index service → SQLite FTS index: writes index (evidence: `NoteSearch/Services/IndexService.swift`)
- Query and snippets → SQLite FTS index: queries FTS (evidence: `README.md`)
- Settings UI → App state: changes settings (evidence: `NoteSearch/Views/SettingsView.swift`)
- Settings UI → Index service: configures index (evidence: `NoteSearch/Views/SettingsView.swift`)
- Settings UI → Global hotkey: configures shortcut (evidence: `NoteSearch/Views/SettingsView.swift`)
- App and panel → Global hotkey: starts handler (evidence: `NoteSearch/NoteSearchApp.swift`)
- App and panel → macOS services: opens files and menus (evidence: `README.md`)
- Query and snippets → App logging: logs search (evidence: `NoteSearch/Services/SearchService.swift`)
- Index service → App logging: logs indexing (evidence: `NoteSearch/Services/IndexService.swift`)
