Imidex

A Windows-native photo management application with AI-powered search capabilities.

Features

• AI-Powered Search: Natural language search using CLIP embeddings
• Similarity Search: Find visually similar photos using ResNet features
• Duplicate Detection: Automatically identify duplicate or near-duplicate photos
• Local-First: All data stored locally, no cloud required
• Zero-Configuration: Single executable, no dependencies to install
• High Performance: Handles 100k+ photos smoothly

Tech Stack

Component	Technology
Desktop Runtime	Tauri v2 (Rust)
Frontend	React 18 + TypeScript
Vector Database	LanceDB
Metadata Store	SQLite
AI Runtime	ONNX Runtime (DirectML/CPU)
Image Processing	Rust native libraries

Prerequisites

1. Node.js (v20 LTS recommended; CI uses 20)

2. Rust (1.75 or later via rustup)

3. WebView2 (included on Windows 11; on Windows 10 install if prompted)

4. Visual Studio Build Tools with MSVC (required to link Rust on Windows): install the Desktop development with C++ workload, then restart the terminal. Example:

   winget install Microsoft.VisualStudio.2022.BuildTools

Repository layout (where things live)

Path	Role
Repository root (imidex/)	package.json, vite.config.ts, frontend src/, npm scripts, Tauri CLI entry
src-tauri/	Rust crate root (Cargo.toml), backend src/, tauri.conf.json, migrations

Most npm and Tauri commands run from the repository root. All Cargo commands run from src-tauri/ (or use --manifest-path src-tauri/Cargo.toml from the root).

---

First-time setup

Run once from the repository root:

npm install

This installs the frontend toolchain and the Tauri CLI (as a dev dependency). Rust dependencies are fetched automatically the first time you run cargo or npm run tauri dev.

---

Development (run the app)

Working directory: repository root

Goal	Command
Full app (Vite + Rust, hot reload)	npm run tauri dev
Frontend only (API calls to Tauri will fail without the app)	npm run dev
Production-like frontend bundle (no server)	npm run build then npm run preview

The dev server uses Vite on port 1420 (see vite.config.ts).

---

Builds

Working directory: repository root

Goal	Command	Output
TypeScript + Vite bundle only	npm run build	dist/
Full desktop installer (MSI/NSIS, etc.)	npm run tauri build	src-tauri/target/release/bundle/ (e.g. msi/, nsis/)

Rust release artifacts also live under src-tauri/target/release/.

---

Unit tests and checks

Rust (backend) — directory: src-tauri

Open a shell, cd into src-tauri, then:

Goal	Command
Run all Rust unit tests	cargo test
Run tests with all features (matches CI)	cargo test --all-features
Run tests for one module (example)	cargo test db::lancedb
Format check	cargo fmt --check
Apply formatting	cargo fmt
Linter (matches CI)	cargo clippy --all-targets --all-features -- -D warnings

From the repository root without changing directory:

cd src-tauri && cargo test

PowerShell:

cd src-tauri; cargo test

Frontend (TypeScript / Vitest) — directory: repository root

Goal	Command
Typecheck only	npm run typecheck
ESLint	npm run lint
Unit tests (Vitest, single run)	npm run test
Unit tests once + coverage (v8, coverage/)	npm run test:coverage

There may be no *.test.ts files yet; test:coverage uses --passWithNoTests so CI still succeeds.

COCO val2017 integration tests (Rust)

26 tests exercise all implemented features against 5000 real JPEGs. They auto-skip when the directory is absent (CI-safe).

• Default path: C:\Users\foste\Pictures\COCO\val2017
• Override: IMIDEX_COCO_DIR env var
• Covers: file hashing, image detection, EXIF extraction, thumbnail generation, full scan pipeline (5000 photos), pagination, library stats, photo CRUD, LanceDB + SQLite consistency, delete cascade, dedup by hash, settings persistence, RAW decoder fallback

cd src-tauri && cargo test --all-features

---

Full quality pass (before a PR)

Run in order from the paths indicated (same as AGENTS.md / CI):

1. Repository root — not required for Rust, but keep npm ci / npm install in sync for frontend steps.

2. src-tauri/:

   cargo fmt --check
   cargo clippy --all-targets --all-features -- -D warnings
   cargo test --all-features

3. Repository root:

   npm run typecheck
   npm run lint
   npm run test

---

Installation (clone and dev)

git clone https://github.com/imidex/imidex.git
cd imidex
npm install
npm run tauri dev

---

Project structure

imidex/
├── src-tauri/           # Rust backend (cd here for cargo)
│   ├── capabilities/    # Tauri v2 plugin permissions (dialog, fs, shell)
│   ├── migrations/      # SQL migrations (user_version)
│   ├── models/          # Bundled resource placeholder (models/*)
│   ├── src/
│   │   ├── commands/    # Tauri IPC handlers
│   │   ├── db/          # SQLite + LanceDB
│   │   ├── services/
│   │   ├── models/
│   │   ├── workers/
│   │   ├── utils/
│   │   └── tests/       # Integration + COCO dataset tests
│   └── Cargo.toml
├── src/                 # React frontend (npm scripts from root)
├── .github/workflows/
└── docs/

Development roadmap

Month 1 — Foundation ✓ Complete

• Project setup
• CI/CD pipeline
• Telemetry infrastructure
• Unit test framework
• SQLite + LanceDB integration
• Photo scanning and EXIF extraction ✓
• Thumbnail generation ✓
• Tauri v2 capabilities (dialog, fs, shell) ✓
• COCO val2017 integration test suite (26 Rust tests + frontend tests) ✓
• BackgroundWorker with task pipeline, retry logic, Tauri events ✓
• File watcher (notify) with debounce + background worker wired to main.rs ✓
• Watcher IPC commands; add_folder/remove_folder interact with watcher ✓
• Photo grid UI with error states, skeleton loading, scan progress bar, per-thumbnail retry ✓
• Tiered RAW decoder (rawloader) with sample validation ✓
• Model download service with resume, verification, and progress UI ✓

Month 2

• ONNX model integration
• CLIP + ResNet embedding pipeline

Month 3

• Text search
• Similarity search
• Duplicate detection

License

MIT License - see LICENSE file for details.