Architecture Overview

Architecture Overview

Look combines a native macOS user interface with an ultra-fast compiled Rust core.

---

1. High-Level Component Stack

┌────────────────────────────────────────────────────────┐
│               macOS UI Shell (SwiftUI / AppKit)        │
│             apps/macos/LauncherApp/look-app            │
└───────────────────────────┬────────────────────────────┘
                            │ C FFI Bridge (C ABI)
                            ▼
┌────────────────────────────────────────────────────────┐
│                     bridge/ffi                         │
│   Memory buffer management, JSON serialization, C ABI  │
└───────────────────────────┬────────────────────────────┘
                            │ Native Rust calls
                            ▼
┌────────────────────────────────────────────────────────┐
│                   Core Rust Crates                     │
│  core/engine   - Query parsing, indexing orchestration │
│  core/calc     - Math, units, timestamps, currency     │
│  core/qactions - Super actions grid and status tiles   │
│  core/storage  - SQLite database persistence           │
│  core/ranking  - Frecency scoring & fuzzy matching     │
│  core/netspeed - Multi-stream speed test engine        │
│  core/todo     - Daily Kanban task database            │
└────────────────────────────────────────────────────────┘

---

2. Core Rust Crates Breakdown

• core/engine: Primary coordinator. Oversees query normalization, scanner threads, candidate caching, and search dispatch.
• core/calc: Parses mathematical queries, unit conversions, currency exchange, and Unix timestamp parsing without external scripting interpreters.
• core/qactions: Resolves layout grids for the Super Actions launchpad from ~/.look/super-actions.toml.
• core/storage: Manages the SQLite database located at ~/Library/Application Support/look/look.db. Handles candidates, usage frequency, and migration schemas.
• core/ranking: Frecency (frequency + recency) ranking model that dynamically promotes frequently selected results.
• bridge/ffi: Exports C-compatible functions (look_search, look_execute_action, look_get_super_actions) consumed by Swift via EngineBridge.swift.

---

3. Query Execution Lifecycle

1. Keystroke Capture: Swift captures input in SmoothCaretTextField with zero UI debounce lag.
2. FFI Call: Swift invokes look_search_json(query) across the C FFI boundary.
3. Core Matching & Scoring:
   • core/engine checks active prefixes (a", f", c", ps", /, ~).
   • core/ranking computes fuzzy alignment scores.
   • Top-K results are returned as a compacted binary payload.
4. Native Render: SwiftUI renders the candidate rows, previews, and icons seamlessly at 120Hz ProMotion refresh rates.