# mdhvg/miscible architecture

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

- Interactive diagram: https://gitdiagram.com/mdhvg/miscible
- Repository: https://github.com/mdhvg/miscible

## Overview

Miscible is an offline local-media gallery with semantic search and filtering. Users add a directory, which the app scans and indexes; the UI then queries and displays images, while semantic search uses downloaded model files and inference embeddings. The graph separates startup, media indexing/storage, inference, and presentation/platform services. Some subsystem links are documented in the README or supported by the source index; unsampled implementation details are not assumed.

Main entry points: [`src/app/miscible.cpp`](https://github.com/mdhvg/miscible/blob/main/src/app/miscible.cpp) (App orchestration), [`src/db/view.cpp`](https://github.com/mdhvg/miscible/blob/main/src/db/view.cpp) (Gallery query views), [`src/scan/scan_dirs.cpp`](https://github.com/mdhvg/miscible/blob/main/src/scan/scan_dirs.cpp) (Directory scanning), [`src/ui/ui_core.cpp`](https://github.com/mdhvg/miscible/blob/main/src/ui/ui_core.cpp) (UI coordination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Application lifecycle"]
  node_entry["Application startup<br/>[main.cpp]"]
  node_app["App orchestration<br/>[miscible.cpp]"]
  node_config["Settings and models<br/>[config.cpp]"]
  node_yaml["YAML settings<br/>[yaml.cpp]"]
end

subgraph group_indexing["Media indexing and storage"]
  node_scan["Directory scanning<br/>[scan_dirs.cpp]"]
  node_atlas["Thumbnail atlas<br/>[scan_atlas.cpp]"]
  node_fetch["Image metadata fetch<br/>[fetch.cpp]"]
  node_db_view["Gallery query views<br/>[view.cpp]"]
  node_db[("SQLite database<br/>[db_helpers.cpp]")]
end

subgraph group_intelligence["Semantic search"]
  node_model["Model management<br/>[model.cpp]"]
  node_clip["CLIP embeddings<br/>[clip.cpp]"]
  node_inference["Inference engine<br/>[inference.cpp]"]
  node_download["Model downloads<br/>[download.cpp]"]
end

subgraph group_presentation["Gallery interface"]
  node_menu["Gallery and filters<br/>[menu.cpp]"]
  node_preview["Image preview<br/>[preview.cpp]"]
  node_ui["UI coordination<br/>[ui_core.cpp]"]
  node_window["Window and rendering<br/>[window.cpp]"]
end

subgraph group_platform["Platform services"]
  node_platform_scan["OS directory scanner"]
  node_os["OS services<br/>[os_inc.cpp]"]
  node_logs["Logging<br/>[log.cpp]"]
end

node_user(("Gallery user"))
node_model_host(("Model host"))

node_user -->|"searches and filters"| node_menu
node_user -->|"adds directory"| node_scan
node_entry -->|"starts"| node_app
node_app -->|"initializes"| node_config
node_app -->|"starts"| node_scan
node_app -->|"starts"| node_atlas
node_app -->|"initializes"| node_inference
node_app -->|"initializes"| node_model
node_app -->|"starts"| node_window
node_app -->|"initializes"| node_ui
node_app -->|"starts"| node_fetch
node_app -->|"initializes"| node_db_view
node_app -->|"uses"| node_yaml
node_app -->|"starts"| node_download
node_app -->|"initializes"| node_logs
node_scan -->|"dispatches"| node_platform_scan
node_scan -->|"updates"| node_db_view
node_scan -->|"uses"| node_fetch
node_scan -->|"uses"| node_model
node_atlas -->|"reads"| node_fetch
node_fetch -->|"queries"| node_db
node_db_view -->|"queries"| node_db
node_db_view -->|"uses"| node_fetch
node_db_view -->|"uses"| node_inference
node_db_view -->|"uses"| node_model
node_menu -->|"queries"| node_db_view
node_menu -->|"uses"| node_scan
node_menu -->|"uses"| node_inference
node_preview -->|"loads metadata"| node_fetch
node_ui -->|"uses"| node_db_view
node_ui -->|"uses"| node_window
node_ui -->|"dispatches"| node_menu
node_ui -->|"uses"| node_os
node_window -->|"renders"| node_ui
node_model -->|"reads settings"| node_config
node_model -->|"uses"| node_clip
node_inference -->|"uses"| node_model
node_inference -->|"uses"| node_clip
node_download -->|"downloads model"| node_model_host
node_os -.->|"provides OS services"| node_platform_scan

click node_entry "https://github.com/mdhvg/miscible/blob/main/src/main.cpp"
click node_app "https://github.com/mdhvg/miscible/blob/main/src/app/miscible.cpp"
click node_config "https://github.com/mdhvg/miscible/blob/main/src/config.cpp"
click node_scan "https://github.com/mdhvg/miscible/blob/main/src/scan/scan_dirs.cpp"
click node_platform_scan "https://github.com/mdhvg/miscible/blob/main/src/os/win32/win32_scan_dirs.cpp"
click node_atlas "https://github.com/mdhvg/miscible/blob/main/src/scan/scan_atlas.cpp"
click node_fetch "https://github.com/mdhvg/miscible/blob/main/src/db/fetch.cpp"
click node_db_view "https://github.com/mdhvg/miscible/blob/main/src/db/view.cpp"
click node_db "https://github.com/mdhvg/miscible/blob/main/src/db/db_helpers.cpp"
click node_menu "https://github.com/mdhvg/miscible/blob/main/src/ui/pages/menu/menu.cpp"
click node_preview "https://github.com/mdhvg/miscible/blob/main/src/ui/pages/preview/preview.cpp"
click node_ui "https://github.com/mdhvg/miscible/blob/main/src/ui/ui_core.cpp"
click node_window "https://github.com/mdhvg/miscible/blob/main/src/window/window.cpp"
click node_model "https://github.com/mdhvg/miscible/blob/main/src/inference/model.cpp"
click node_clip "https://github.com/mdhvg/miscible/blob/main/src/inference/clip.cpp"
click node_inference "https://github.com/mdhvg/miscible/blob/main/src/inference/inference.cpp"
click node_download "https://github.com/mdhvg/miscible/blob/main/src/network/download.cpp"
click node_os "https://github.com/mdhvg/miscible/blob/main/src/os/os_inc.cpp"
click node_yaml "https://github.com/mdhvg/miscible/blob/main/src/yaml.cpp"
click node_logs "https://github.com/mdhvg/miscible/blob/main/src/base/log.cpp"

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,node_config,node_yaml,node_user toneBlue
class node_scan,node_atlas,node_fetch,node_db_view,node_db toneAmber
class node_model,node_clip,node_inference,node_download toneMint
class node_menu,node_preview,node_ui,node_window toneRose
class node_platform_scan,node_os,node_logs,node_model_host toneIndigo
```

## Components

### Application lifecycle

- [Application startup](https://github.com/mdhvg/miscible/blob/main/src/main.cpp): `src/main.cpp`
- [App orchestration](https://github.com/mdhvg/miscible/blob/main/src/app/miscible.cpp): `src/app/miscible.cpp`
- [Settings and models](https://github.com/mdhvg/miscible/blob/main/src/config.cpp): `src/config.cpp`
- [YAML settings](https://github.com/mdhvg/miscible/blob/main/src/yaml.cpp): `src/yaml.cpp`

### Media indexing and storage

- [Directory scanning](https://github.com/mdhvg/miscible/blob/main/src/scan/scan_dirs.cpp): `src/scan/scan_dirs.cpp`
- [Thumbnail atlas](https://github.com/mdhvg/miscible/blob/main/src/scan/scan_atlas.cpp): `src/scan/scan_atlas.cpp`
- [Image metadata fetch](https://github.com/mdhvg/miscible/blob/main/src/db/fetch.cpp): `src/db/fetch.cpp`
- [Gallery query views](https://github.com/mdhvg/miscible/blob/main/src/db/view.cpp): `src/db/view.cpp`
- [SQLite database](https://github.com/mdhvg/miscible/blob/main/src/db/db_helpers.cpp): `src/db/db_helpers.cpp`

### Semantic search

- [Model management](https://github.com/mdhvg/miscible/blob/main/src/inference/model.cpp): `src/inference/model.cpp`
- [CLIP embeddings](https://github.com/mdhvg/miscible/blob/main/src/inference/clip.cpp): `src/inference/clip.cpp`
- [Inference engine](https://github.com/mdhvg/miscible/blob/main/src/inference/inference.cpp): `src/inference/inference.cpp`
- [Model downloads](https://github.com/mdhvg/miscible/blob/main/src/network/download.cpp): `src/network/download.cpp`

### Gallery interface

- [Gallery and filters](https://github.com/mdhvg/miscible/blob/main/src/ui/pages/menu/menu.cpp): `src/ui/pages/menu/menu.cpp`
- [Image preview](https://github.com/mdhvg/miscible/blob/main/src/ui/pages/preview/preview.cpp): `src/ui/pages/preview/preview.cpp`
- [UI coordination](https://github.com/mdhvg/miscible/blob/main/src/ui/ui_core.cpp): `src/ui/ui_core.cpp`
- [Window and rendering](https://github.com/mdhvg/miscible/blob/main/src/window/window.cpp): `src/window/window.cpp`

### Platform services

- [OS directory scanner](https://github.com/mdhvg/miscible/blob/main/src/os/win32/win32_scan_dirs.cpp): `src/os/win32/win32_scan_dirs.cpp`
- [OS services](https://github.com/mdhvg/miscible/blob/main/src/os/os_inc.cpp): `src/os/os_inc.cpp`
- [Logging](https://github.com/mdhvg/miscible/blob/main/src/base/log.cpp): `src/base/log.cpp`

### Other components

- **Gallery user**
- **Model host**

## Connections

- Gallery user → Gallery and filters: searches and filters
- Gallery user → Directory scanning: adds directory
- Application startup → App orchestration: starts (evidence: `src/main.cpp`)
- App orchestration → Settings and models: initializes (evidence: `src/app/miscible.cpp`)
- App orchestration → Directory scanning: starts (evidence: `src/app/miscible.cpp`)
- App orchestration → Thumbnail atlas: starts (evidence: `src/app/miscible.cpp`)
- App orchestration → Inference engine: initializes (evidence: `src/app/miscible.cpp`)
- App orchestration → Model management: initializes (evidence: `src/app/miscible.cpp`)
- App orchestration → Window and rendering: starts (evidence: `src/app/miscible.cpp`)
- App orchestration → UI coordination: initializes (evidence: `src/app/miscible.cpp`)
- App orchestration → Image metadata fetch: starts (evidence: `src/app/miscible.cpp`)
- App orchestration → Gallery query views: initializes (evidence: `src/app/miscible.cpp`)
- App orchestration → YAML settings: uses (evidence: `src/app/miscible.cpp`)
- App orchestration → Model downloads: starts (evidence: `src/app/miscible.cpp`)
- App orchestration → Logging: initializes (evidence: `src/app/miscible.cpp`)
- Directory scanning → OS directory scanner: dispatches (evidence: `src/scan/scan_dirs.cpp`)
- Directory scanning → Gallery query views: updates (evidence: `src/scan/scan_dirs.cpp`)
- Directory scanning → Image metadata fetch: uses (evidence: `src/scan/scan_dirs.cpp`)
- Directory scanning → Model management: uses (evidence: `src/scan/scan_dirs.cpp`)
- Thumbnail atlas → Image metadata fetch: reads (evidence: `src/scan/scan_atlas.cpp`)
- Image metadata fetch → SQLite database: queries (evidence: `src/db/fetch.cpp`)
- Gallery query views → SQLite database: queries (evidence: `src/db/view.cpp`)
- Gallery query views → Image metadata fetch: uses (evidence: `src/db/view.cpp`)
- Gallery query views → Inference engine: uses (evidence: `src/db/view.cpp`)
- Gallery query views → Model management: uses (evidence: `src/db/view.cpp`)
- Gallery and filters → Gallery query views: queries (evidence: `src/ui/pages/menu/menu.cpp`)
- Gallery and filters → Directory scanning: uses (evidence: `src/ui/pages/menu/menu.cpp`)
- Gallery and filters → Inference engine: uses (evidence: `src/ui/pages/menu/menu.cpp`)
- Image preview → Image metadata fetch: loads metadata (evidence: `src/ui/pages/preview/preview.cpp`)
- UI coordination → Gallery query views: uses (evidence: `src/ui/ui_core.cpp`)
- UI coordination → Window and rendering: uses (evidence: `src/ui/ui_core.cpp`)
- UI coordination → Gallery and filters: dispatches (evidence: `src/ui/ui_core.cpp`)
- UI coordination → OS services: uses (evidence: `src/ui/ui_core.cpp`)
- Window and rendering → UI coordination: renders (evidence: `src/window/window.cpp`)
- Model management → Settings and models: reads settings
- Model management → CLIP embeddings: uses
- Inference engine → Model management: uses (evidence: `src/inference/inference.cpp`)
- Inference engine → CLIP embeddings: uses (evidence: `src/inference/inference.cpp`)
- Model downloads → Model host: downloads model
- OS services → OS directory scanner: provides OS services
