Flow.Launcher/Flow.Launcher.Infrastructure/codemap.md

Flow.Launcher.Infrastructure/

The Infrastructure project provides the foundational services, utilities, and shared models used across the Flow.Launcher ecosystem. It serves as a bridge between high-level application logic and low-level system interactions.

Responsibility

• Persistence & Storage: Manages serialization and deserialization of application data and settings using robust JSON/Binary storage mechanisms.
• Fuzzy Matching: Implements the core search logic, including fuzzy string matching, acronym detection, and multi-language support (e.g., Pinyin).
• Global Hotkey Management: Intercepts and processes system-wide keyboard events using low-level Windows hooks.
• Configuration: Provides a centralized, reactive Settings model that drives the application's behavior and appearance.
• Logging: Offers a unified logging interface wrapping NLog for error reporting and debugging.
• System Integration: Wraps complex Win32 API calls and provides helpers for file system operations, image processing, and environment management.

Design Patterns

• Persistence Framework (Generic Storage): JsonStorage<T> uses a generic approach to provide consistent serialization logic, including atomic writes and backup recovery.
• Reactive Model: The Settings class uses the MVVM pattern (via CommunityToolkit.Mvvm) to notify the UI of configuration changes.
• Static Service/Singleton: Core utilities like Log, DataLocation, and Win32Helper are implemented as static services for global accessibility.
• Dependency Injection: Services like StringMatcher are registered and resolved via CommunityToolkit.Mvvm.DependencyInjection to decouple components.
• Template Method: JsonStorage<T> defines the save/load algorithm, while derived classes like FlowLauncherJsonStorage<T> specialize the storage location.

Key Classes

Configuration & Data

• UserSettings.Settings: The primary configuration model. It implements IHotkeySettings and holds hundreds of user-configurable properties. It is reactive, triggering UI updates immediately upon property change.
• UserSettings.DataLocation: Encapsulates the logic for determining where application data is stored (Roaming vs. Portable mode).
• Constant: Centralized repository for application-wide constants, paths, and URLs.

Search Engine

• StringMatcher: The heart of Flow's search capability. It combines acronym matching and fuzzy substring matching. It supports search precision tuning and leverages IAlphabet for localized character translation.
• MatchResult: A model representing the outcome of a search match, containing the score and the indices of matched characters for UI highlighting.

Storage Systems

• Storage.JsonStorage<T>: A robust JSON storage implementation featuring:
  • Atomic Writes: Uses .tmp files and File.Replace to prevent data corruption during crashes.
  • Backup System: Automatically maintains .bak files and timestamped backups if loading fails.
• Storage.FlowLauncherJsonStorage<T>: A specialization of JsonStorage that automatically routes files to the appropriate UserData directory.

Logging & Diagnostics

• Logger.Log: A static wrapper for NLog. It supports asynchronous file logging and debug string output. It includes a Demystify step for exception stacks to make them more readable.
• Stopwatch: High-resolution timing utility for performance profiling.

Input & System

• Hotkey.GlobalHotkey: Manages low-level WH_KEYBOARD_LL hooks to intercept hotkeys before they reach other applications.
• Win32Helper: Provides a clean C# interface for complex P/Invoke operations, including window management, shell execution, and system font retrieval.

Data & Control Flow

Search & Result Flow

1. Input: A query string enters from the UI.
2. Preprocessing: StringMatcher trims the query and optionally translates it via PinyinAlphabet or other IAlphabet implementations.
3. Matching:
   • Acronym Match: Checks if query characters match the starts of words or uppercase letters.
   • Fuzzy Match: Performs substring matching and character distance calculation.
4. Scoring: A score is calculated based on match length, position, and closeness of characters.
5. Output: A MatchResult is returned to the PluginManager to be ranked against other results.

Settings Lifecycle

1. Loading: On startup, FlowLauncherJsonStorage<Settings> reads Settings.json. If corrupt, it attempts to restore from Settings.json.bak.
2. Injection: The Settings instance is registered in the Ioc container.
3. Modification: UI components bind to Settings properties. Changes trigger OnPropertyChanged.
4. Persistence: The Save() method is called (often triggered by application exit or manual save), executing an atomic write to disk.

Integration Points

• NLog: Backend for the Log service.
• CommunityToolkit.Mvvm: Used for the Ioc container and ObservableObject base classes.
• CsWin32 / PInvoke: Deep integration with Windows APIs for hotkeys, file explorer interaction, and UI rendering hints.
• Flow.Launcher.Plugin: Infrastructure provides the concrete implementations for many interfaces defined in the Plugin SDK.
• System.Text.Json: The primary serialization engine for all storage components.