How archdex-art/supersearch works
1. Overall shape
SuperSearch is a macOS desktop app built as a Tauri shell around a Rust “runtime kernel.” The main architecture boundary is between a thin frontend/UI layer and a Rust backend that performs search, intent parsing, orchestration, OS automation, and auditing.
2. Frontend layer
The production UI lives in ui/ and is plain HTML/CSS/JavaScript. It renders the command palette, previews, settings, and keyboard handling, then talks to the Tauri backend through IPC. There is also a separate react-command-palette/ app that looks like a prototype/demo UI, not the primary runtime surface.
3. Tauri host layer
src-tauri/ is the app host. It exposes command modules for search, agent actions, extensions, journal, settings, telemetry, updater, and window control. This layer is the bridge between the UI and the runtime kernel, and it also owns app state and macOS window/hotkey behavior.
4. Core runtime kernel
crates/supersearch-runtime/ is the main engine. It is organized into:
- agent/ for intent understanding and execution planning
- capability/ for permission gating
- journal/ for audit/replay
- extension/ and plugin/ for extensibility
- scheduler/ and reactive/ for future orchestration/reactivity
- platform/ and kernel/ for OS-specific process/runtime plumbing
The README makes clear that the load-bearing path today is the agent + capability + journal path.
5. Intent-to-action flow
Natural-language commands enter through the UI, reach the Tauri agent command, and are processed by the runtime’s patterns.rs classifier. The classifier maps text into a closed set of intents; planner.rs turns those intents into a TaskGraph; executor.rs runs the graph step by step. This is intentionally deterministic and replayable rather than LLM-generated code execution.
6. OS automation path
The executor ultimately drives macOS through direct process spawning and AppleScript-based automation. The runtime uses helper commands such as open, mdfind, osascript, pbcopy, and terminal/app launching flows. The architecture is local-first and argument-vector based, so user input is not interpolated into shell strings.
7. Capability and security boundary
Before any OS action runs, the executor consults capability/ to check whether the current token authorizes the requested (namespace, permission). The agent gets a revocable token in the agent namespace; extensions get their own scoped tokens. This gate is the main security boundary between “planned action” and “touching the OS.”
8. Journal and audit trail
journal/ records capability checks and OS automation results in an append-only log. That makes the execution path inspectable and replayable, and it is part of the architecture rather than a debugging aid. For a diagram, this is the persistence/audit side-channel connected to the executor and gate.
9. Search and system discovery
Search is handled primarily in the Tauri backend via commands like search.rs and system_search.rs, with fuzzy matching over installed applications, local files, and system actions. This is separate from the agent pipeline: search is the “find something fast” path, while the agent is the “interpret intent and execute steps” path.
10. Extensions and plugins
Extensions are manifest-driven directories installed under the user’s Application Support folder. The runtime supports two models: native script extensions and sandboxed WASM extensions. Both are mediated by the same capability model, and extension actions are checked before they can reach the OS. The src-tauri commands expose the extension management surface for list/install/enable/query/execute flows.
11. Platform abstraction
The runtime includes platform/linux.rs, platform/macos.rs, platform/windows.rs, and platform/unsupported.rs, plus platform/exec.rs. Architecturally this is a portability boundary, but the product is effectively macOS-first because Apple Events and osascript are central to the automation model.
12. Not-yet-load-bearing subsystems
scheduler/ and reactive/ exist as real subsystems, but the README says they are not yet load-bearing for first-party agent actions. They are best treated as future orchestration/context machinery, not part of the critical execution path for the current app.
13. Deployment and operational edge
The app is packaged as a native macOS Tauri app, with GitHub Actions workflows for CI and release. The runtime also depends on macOS Accessibility permissions for simulated input and Apple Events, so the OS permission boundary is part of the effective architecture.
Main entry points: commands/mod.rs Commands · executor.rs Executor · bridge.js IPC bridge · kernel/mod.rs Kernel
Components 22
Frontend
UI surfaces and browser-side logic
- UI app · Primary production command palette and settings UI
ui/scripts/app.js - Search UI · Search input, result ranking, and selection handling
ui/scripts/search.js - Agent UI · Command parsing and execution entry from the palette
ui/scripts/agent.js - IPC bridge · Frontend messaging layer into the native backend
ui/scripts/bridge.js
Tauri Host
Desktop app bridge and command surface
- Commands · Native command surface for search, agent, extensions, journal, settings, telemetry, updater, and window control
src-tauri/src/commands/mod.rs - Agent cmd · Entry point for intent execution requests
src-tauri/src/commands/agent.rs - Search cmd · Search and system discovery entry points
src-tauri/src/commands/search.rs - Extensions cmd · Extension management and execution surface
src-tauri/src/commands/extensions.rs - Journal cmd · Audit and replay access from the host layer
src-tauri/src/commands/journal.rs - App state · Shared state, settings, and window lifecycle coordination
src-tauri/src/state.rs
Runtime Kernel
Core intent, security, execution, and extensibility engine
- Agent core · Intent understanding, planning, and stepwise execution
crates/supersearch-runtime/src/agent/mod.rs - Patterns · Maps text into a closed intent set
crates/supersearch-runtime/src/agent/patterns.rs - Planner · Converts intents into executable task graphs
crates/supersearch-runtime/src/agent/planner.rs - Executor · Runs planned tasks against capability gates and OS actions
crates/supersearch-runtime/src/agent/executor.rs - Capability gate · Namespace and permission authorization before OS actions
crates/supersearch-runtime/src/capability/gate.rs - Journal · Append-only execution record and replay trail
crates/supersearch-runtime/src/journal/mod.rs - Extensions · Manifest-driven native and WASM extension hosting
crates/supersearch-runtime/src/extension/mod.rs - Platform · Cross-platform process and automation boundary
crates/supersearch-runtime/src/platform/mod.rs - Kernel · Process/runtime plumbing for the engine
crates/supersearch-runtime/src/kernel/mod.rs - Reactive · Signal graph and reconciliation layer not yet load-bearing
crates/supersearch-runtime/src/reactive/mod.rs - Scheduler · Task scheduling and prioritization subsystem not yet central
crates/supersearch-runtime/src/scheduler/mod.rs
Ops
Build, release, and deployment boundary
- CI/CD · Automated build and release workflows
.github/workflows/release.yml
Connections 25
- UI app → IPC bridge: events · UI interactions are forwarded through the bridge
- Search UI → IPC bridge: search · Search requests flow into backend commands
- Agent UI → IPC bridge: intent · Natural-language commands are sent to the native backend
- IPC bridge → Commands: IPC · Bridge dispatches into Tauri commands
- Commands → Agent cmd: agent · Exposes agent execution entry point
- Commands → Search cmd: search · Exposes search and discovery entry point
- Commands → Extensions cmd: extensions · Exposes extension management and execution
- Commands → Journal cmd: journal · Exposes audit and replay access
- Commands → App state: state · Commands coordinate through shared app state
- Agent cmd → Agent core: invoke · Agent requests enter the runtime kernel
- Search cmd → Agent core: discover · Search can delegate into runtime-backed discovery
- Agent core → Patterns: classify · Text is classified into intents
- Patterns → Planner: intent · Matched intents are converted into task plans
- Planner → Executor: task graph · Planned steps are handed to the executor
- Executor → Capability gate: authorize · Every OS action is checked against permissions
- Executor → Platform: os action · Executor drives local automation through platform helpers
- Executor → Journal: audit · Capability checks and outcomes are recorded
- Extensions → Capability gate: scope · Extension actions are mediated by the same gate
- Extensions → Platform: host · Native and WASM extensions ultimately run through platform services
- Platform → Kernel: runtime · Platform-specific process plumbing is managed by the kernel
- Kernel → Scheduler: future · Kernel exposes scheduling-oriented runtime support
- Kernel → Reactive: future · Kernel exposes reactive orchestration support
- Extensions cmd → Extensions: manage · Host commands manage installed extensions
- Journal cmd → Journal: read · Host commands read audit records and replay data
- CI/CD → Commands: ship · CI and release workflows package the native app