# just-a-freshman/vimgfind architecture

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

- Interactive diagram: https://gitdiagram.com/just-a-freshman/vimgfind
- Repository: https://github.com/just-a-freshman/vimgfind

## Overview

VimgFind is a local AI image-search desktop application. Users add image folders, build or incrementally update a model-specific index, then search with an image or text and refine results with filters. The main path is visible in the sampled search and index controllers; the README documents additional model management, exclusion rules, custom context commands, tray behavior, and automatic updates. Several UI/controller connections and those additional features are represented from the tree and README, since their implementation was not sampled.

Main entry points: [`core/search_engine.py`](https://github.com/just-a-freshman/vimgfind/blob/version2.5/core/search_engine.py) (Search Engine), [`config/settings.py`](https://github.com/just-a-freshman/vimgfind/blob/version2.5/config/settings.py) (Settings), [`controllers/search_controller.py`](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/search_controller.py) (Search Controller), [`controllers/index_controller.py`](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/index_controller.py) (Index Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop Application"]
  node_entry["Application Entry<br/>[main.py]"]
  node_app_controller["App Controller<br/>[app_controller.py]"]
  node_main_window["Main Window<br/>[main_window.py]"]
  node_search_ui["Search Page<br/>[search_page.py]"]
  node_index_ui["Index Page<br/>[index_page.py]"]
  node_result_views["Search Result Views<br/>[preview_canvas.py]"]
end

subgraph group_search["Search and Index"]
  node_search_controller["Search Controller"]
  node_filter_controller["Filter Controller"]
  node_search_engine["Search Engine<br/>[search_engine.py]"]
  node_index_controller["Index Controller"]
  node_encoder["Multimodal Encoder"]
  node_index_store[("Vector and Name Indexes<br/>[index_manager.py]")]
end

subgraph group_models["Models and Settings"]
  node_model_controller["Model Controller"]
  node_model_ui["Model Page<br/>[model_page.py]"]
  node_settings["Settings<br/>[settings.py]"]
  node_remote_catalog["Model Catalog"]
end

subgraph group_features["User Features"]
  node_exclude_controller["Exclusion Rules"]
  node_menu_controller["Context Commands<br/>[menu_controller.py]"]
  node_tray_controller["System Tray<br/>[tray_controller.py]"]
  node_update_controller["Application Updates"]
  node_setting_controller["General Settings"]
end

node_user(("User"))

node_user -->|"launches"| node_entry
node_entry -->|"creates"| node_app_controller
node_app_controller -->|"creates"| node_main_window
node_user -->|"enters query"| node_search_ui
node_user -->|"chooses folders"| node_index_ui
node_search_ui -->|"submits query"| node_search_controller
node_search_controller -->|"runs search"| node_search_engine
node_search_controller -->|"applies filters"| node_filter_controller
node_search_controller -->|"shows results"| node_result_views
node_search_engine -->|"encodes query"| node_encoder
node_search_engine -->|"queries indexes"| node_index_store
node_index_ui -->|"requests update"| node_index_controller
node_index_controller -->|"updates index"| node_search_engine
node_search_engine -->|"writes vectors and names"| node_index_store
node_search_engine -->|"encodes images"| node_encoder
node_index_controller -->|"reads configuration"| node_settings
node_search_engine -->|"reads model settings"| node_settings
node_model_ui -->|"manages models"| node_model_controller
node_model_controller -.->|"fetches catalog"| node_remote_catalog
node_model_controller -->|"saves model config"| node_settings
node_exclude_controller -->|"configures exclusions"| node_settings
node_index_controller -->|"applies exclusions"| node_exclude_controller
node_menu_controller -->|"acts on selections"| node_result_views
node_tray_controller -->|"controls visibility"| node_main_window
node_setting_controller -->|"updates preferences"| node_settings
node_update_controller -.->|"checks releases"| node_remote_catalog

click node_entry "https://github.com/just-a-freshman/vimgfind/blob/version2.5/main.py"
click node_app_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/app_controller.py"
click node_main_window "https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/main_window.py"
click node_search_ui "https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/search_page.py"
click node_index_ui "https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/index_page.py"
click node_search_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/search_controller.py"
click node_filter_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/search_controller.py"
click node_search_engine "https://github.com/just-a-freshman/vimgfind/blob/version2.5/core/search_engine.py"
click node_index_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/index_controller.py"
click node_encoder "https://github.com/just-a-freshman/vimgfind/blob/version2.5/core/multimodal_encoder.py"
click node_index_store "https://github.com/just-a-freshman/vimgfind/blob/version2.5/core/index_manager.py"
click node_model_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/model_controller.py"
click node_model_ui "https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/model_page.py"
click node_settings "https://github.com/just-a-freshman/vimgfind/blob/version2.5/config/settings.py"
click node_result_views "https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/widgets/preview_canvas.py"
click node_exclude_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/exclude_controller.py"
click node_menu_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/menu_controller.py"
click node_tray_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/tray_controller.py"
click node_update_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/update_controller.py"
click node_setting_controller "https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/setting_controller.py"

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_entry,node_app_controller,node_main_window,node_search_ui,node_index_ui,node_result_views,node_user toneBlue
class node_search_controller,node_filter_controller,node_search_engine,node_index_controller,node_encoder,node_index_store toneAmber
class node_model_controller,node_model_ui,node_settings,node_remote_catalog toneMint
class node_exclude_controller,node_menu_controller,node_tray_controller,node_update_controller,node_setting_controller toneRose
```

## Components

### Desktop Application

- [Application Entry](https://github.com/just-a-freshman/vimgfind/blob/version2.5/main.py): `main.py`
- [App Controller](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/app_controller.py): `controllers/app_controller.py`
- [Main Window](https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/main_window.py): `views/main_window.py`
- [Search Page](https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/search_page.py): `views/search_page.py`
- [Index Page](https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/index_page.py): `views/index_page.py`
- [Search Result Views](https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/widgets/preview_canvas.py): `views/widgets/preview_canvas.py`

### Search and Index

- [Search Controller](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/search_controller.py): `controllers/search_controller.py`
- [Filter Controller](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/search_controller.py): `controllers/search_controller.py`
- [Search Engine](https://github.com/just-a-freshman/vimgfind/blob/version2.5/core/search_engine.py): `core/search_engine.py`
- [Index Controller](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/index_controller.py): `controllers/index_controller.py`
- [Multimodal Encoder](https://github.com/just-a-freshman/vimgfind/blob/version2.5/core/multimodal_encoder.py): `core/multimodal_encoder.py`
- [Vector and Name Indexes](https://github.com/just-a-freshman/vimgfind/blob/version2.5/core/index_manager.py): `core/index_manager.py`

### Models and Settings

- [Model Controller](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/model_controller.py): `controllers/model_controller.py`
- [Model Page](https://github.com/just-a-freshman/vimgfind/blob/version2.5/views/model_page.py): `views/model_page.py`
- [Settings](https://github.com/just-a-freshman/vimgfind/blob/version2.5/config/settings.py): `config/settings.py`
- **Model Catalog**

### User Features

- [Exclusion Rules](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/exclude_controller.py): `controllers/exclude_controller.py`
- [Context Commands](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/menu_controller.py): `controllers/menu_controller.py`
- [System Tray](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/tray_controller.py): `controllers/tray_controller.py`
- [Application Updates](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/update_controller.py): `controllers/update_controller.py`
- [General Settings](https://github.com/just-a-freshman/vimgfind/blob/version2.5/controllers/setting_controller.py): `controllers/setting_controller.py`

### Other components

- **User**

## Connections

- User → Application Entry: launches
- Application Entry → App Controller: creates
- App Controller → Main Window: creates
- User → Search Page: enters query
- User → Index Page: chooses folders
- Search Page → Search Controller: submits query
- Search Controller → Search Engine: runs search
- Search Controller → Filter Controller: applies filters
- Search Controller → Search Result Views: shows results
- Search Engine → Multimodal Encoder: encodes query
- Search Engine → Vector and Name Indexes: queries indexes
- Index Page → Index Controller: requests update
- Index Controller → Search Engine: updates index
- Search Engine → Vector and Name Indexes: writes vectors and names
- Search Engine → Multimodal Encoder: encodes images
- Index Controller → Settings: reads configuration
- Search Engine → Settings: reads model settings
- Model Page → Model Controller: manages models
- Model Controller → Model Catalog: fetches catalog
- Model Controller → Settings: saves model config
- Exclusion Rules → Settings: configures exclusions
- Index Controller → Exclusion Rules: applies exclusions
- Context Commands → Search Result Views: acts on selections
- System Tray → Main Window: controls visibility
- General Settings → Settings: updates preferences
- Application Updates → Model Catalog: checks releases