Backend Architecture

The Xplorer backend is written in Rust and runs as the main process of the Tauri v2 application. It handles all file system operations, AI integration, SSH connections, and more.

Module Structure

Core Entry Point

main.rs — Registers 100+ Tauri commands and initializes all subsystems:

fn main() {
    dotenv::dotenv().ok();
    init_shortcuts_manager();

    tauri::Builder::default()
        .plugin(tauri_plugin_fs::init())
        .plugin(tauri_plugin_global_shortcut::Builder::new().build())
        .plugin(tauri_plugin_dialog::init())
        .invoke_handler(tauri::generate_handler![
            // 100+ command registrations...
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

File Operations (`operations/`)

The largest module, handling all filesystem interactions:

| File | Responsibility | |------|---------------| | types.rs | Shared types (FileEntry, FileProperties, OperationProgress) | | directory_ops.rs | read_directory, create_directory, get_files_in_directory | | file_ops.rs | copy_with_progress, move_with_progress, rename, delete_files | | trash_ops.rs | get_trash_items, restore_from_trash, empty_trash | | metadata_ops.rs | get_file_metadata, file size/date retrieval | | properties_ops.rs | get_detailed_file_properties (MIME type, dimensions, hashes) | | compression_ops.rs | ZIP/TAR/GZ/BZ2/XZ compress and extract | | accelerated_ops.rs | SIMD-optimized and memory-mapped file copy | | comparison_ops.rs | Text and binary file comparison/diff | | system_ops.rs | Drive listing, system information | | progress.rs | Operation progress tracking with event emission | | agent_ops.rs | AI agent file read/write operations | | file_associations_ops.rs | OS file associations and default apps | | undo_redo_ops.rs | Undo/redo operation recording and replay | | analytics_ops.rs | Storage analytics and usage statistics |

AI Integration

| File | Responsibility | |------|---------------| | ai.rs | Ollama chat API, file analysis, directory analysis | | agent/mod.rs | Claude AI agent entry point | | agent/tools.rs | Agent tool definitions (file read, write, search, etc.) | | agent/tool_executor.rs | Tool invocation and result handling | | agent/streaming.rs | Streaming response handling for real-time output | | agent/planner.rs | Multi-step task planning and decomposition | | agent/memory.rs | Conversation memory and context management | | agent/security.rs | Path traversal guards and system directory blocking | | file_organizer.rs | AI-powered file categorization and organization suggestions |

Search & Indexing (`search/`)

The search engine is a full module with multiple specialized sub-components:

| File | Responsibility | |------|---------------| | mod.rs | Search module entry point, public API | | index.rs | Inverted index construction and management | | query_parser.rs | Query parsing, structured queries with filters (file_type, size, date, extension) | | fuzzy.rs | Fuzzy matching for typo-tolerant search | | stemmer.rs | Word stemming for root-form matching | | synonyms.rs | Synonym expansion for broader recall | | hybrid.rs | Hybrid keyword + semantic search combining BM25F and embeddings | | bm25f.rs | BM25F field-weighted scoring algorithm | | fst_index.rs | FST-based fast prefix/substring lookup | | segment.rs | Index segmentation for large datasets | | bitmap_filters.rs | Bitmap-based metadata filtering (type, size, date) | | context_ranker.rs | Context-aware result ranking | | reranker.rs | Result reranking with multiple signals | | ai_pipeline.rs | AI-augmented search (vision descriptions, embeddings) | | ollama_client.rs | Ollama embedding API client for semantic search | | watcher.rs | File system watcher for automatic index updates | | compat.rs | Backward compatibility with legacy tokenizer API |

Search Pipeline:
1. Parse query via query_parser (structured filters + keywords)
2. Fuzzy match and stem keywords
3. Expand with synonyms
4. Look up terms in inverted index + FST index
5. Apply bitmap filters (file type, size range, date range)
6. Score with BM25F field-weighted algorithm
7. Optionally run semantic search via Ollama embeddings
8. Merge results with hybrid scoring
9. Rerank with context_ranker and reranker
10. Return ranked results

Features:

Incremental indexing — Only re-indexes changed files (by timestamp + size)
Document extraction — Extracts text from PDF, DOCX, XLSX, PPTX (via document_extractor.rs)
Natural language search — Parses queries like "large videos from last month"
AI-augmented search — Vision-generated descriptions and embeddings are searchable
Fuzzy + stemming — Typo-tolerant and root-form matching
Hybrid scoring — Combines keyword BM25F with semantic similarity

SSH/SFTP (`ssh.rs`)

Full SSH remote filesystem support:

// Connection management
ssh_connect(connection) -> SSHConnectionResult
ssh_disconnect(connection_id)
list_ssh_connections() -> Vec<SSHConnection>

// File operations
ssh_list_directory(connection_id, path) -> Vec<FileEntry>
ssh_read_file(connection_id, path) -> String
ssh_upload_file(connection_id, local, remote)
ssh_download_file(connection_id, remote, local)
ssh_create_directory(connection_id, path)
ssh_delete(connection_id, path)

Uses the ssh2 crate with a connection pool and session caching.

Git Integration (`git_history.rs` + `git_integration.rs`)

Interfaces with git repositories using the git2 crate for native libgit2 bindings:

git_history.rs — History, blame, and branch operations:

get_commit_history — Full commit log with pagination
get_file_history — History of a specific file
get_file_blame — Line-by-line blame annotations
get_file_diff / get_commit_diff — Unified diff output
get_branches / switch_branch / create_branch — Branch management
get_stash_list / stash_changes / pop_stash — Stash operations
get_git_status — Working tree status

git_integration.rs — Remote operations:

git_pull — Pull from remote with merge
git_push — Push local commits to remote
git_fetch — Fetch from remote without merge
git_get_remotes — List configured remotes (name, url, push_url)

Storage (`storage/`)

Persistent local data storage, split into focused sub-modules:

| File | Responsibility | |------|---------------| | mod.rs | Storage module entry point and shared utilities | | bookmarks.rs | Bookmark/favorites management (BookmarkEntry, add/remove/update) | | tags.rs | File tagging system (FileTag, get/set/remove tags) | | notes.rs | File notes and annotations | | metadata.rs | Custom metadata storage per file | | recent.rs | Recent files and directories tracking | | extensions_storage.rs | Key-value storage for extension data persistence |

Google Drive (`google_drive.rs` + `secure_credentials.rs`)

Google Drive cloud storage integration:

google_drive.rs — Full Google Drive file operations: authenticate, list accounts, list/download/upload/delete/rename/move files, create folders, read file content, settings management
secure_credentials.rs — Secure OAuth token storage using OS credential store (Windows Credential Manager / macOS Keychain)

Extension System (`extensions/`)

| File | Responsibility | |------|---------------| | types.rs | ExtensionManifest, Extension, ExtensionStatus | | manager.rs | Install, activate, deactivate, uninstall extensions | | permissions.rs | Permission definitions and validation | | commands.rs | Tauri commands for extension management | | signing.rs | Extension code signing and signature verification | | native_plugin.rs | Native plugin loading and execution |

Extension Watcher (`extension_watcher.rs`)

Uses the notify crate for file system watching to enable hot-reload of extensions during development. Monitors extension directories for changes and triggers re-loading automatically.

Keyboard Shortcuts (`shortcuts/`)

| File | Responsibility | |------|---------------| | types.rs | ShortcutProfile, Shortcut, ShortcutAction | | manager.rs | Profile management, conflict detection, persistence |

Key Design Patterns

Error Handling

All Tauri commands return Result<T, String> where errors are user-friendly messages:

#[tauri::command]
async fn read_directory(path: &str) -> Result<Vec<FileEntry>, String> {
    // ... implementation
    Err(format!("Failed to read directory: {}", e))
}

Concurrency

Tokio runtime for async operations (SSH, AI API calls)
Rayon for parallel CPU-bound work (duplicate finder, directory scanning)
Mutex/RwLock for shared state (tokenizer index, SSH connection pool)

File Copy Strategies

The accelerated ops module selects the optimal copy strategy based on file size and hardware:

File Size < 1MB     → Standard std::fs::copy
File Size 1-100MB   → Buffered copy with optimal buffer size
File Size > 100MB   → Memory-mapped copy (if supported)
Directory copy      → Parallel copy with rayon thread pool

Backend Architecture

Backend Architecture

Module Structure

Core Entry Point

File Operations (operations/)

AI Integration

Search & Indexing (search/)

SSH/SFTP (ssh.rs)

Git Integration (git_history.rs + git_integration.rs)

Storage (storage/)

Google Drive (google_drive.rs + secure_credentials.rs)

Extension System (extensions/)

Extension Watcher (extension_watcher.rs)

Keyboard Shortcuts (shortcuts/)

Key Design Patterns

Error Handling

Concurrency

File Copy Strategies

File Operations (`operations/`)

Search & Indexing (`search/`)

SSH/SFTP (`ssh.rs`)

Git Integration (`git_history.rs` + `git_integration.rs`)

Storage (`storage/`)

Google Drive (`google_drive.rs` + `secure_credentials.rs`)

Extension System (`extensions/`)

Extension Watcher (`extension_watcher.rs`)

Keyboard Shortcuts (`shortcuts/`)