# archdex-art/supersearch architecture

> Architecture diagram of the GitHub repository archdex-art/supersearch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/archdex-art/supersearch
- Repository: https://github.com/archdex-art/supersearch

## Overview

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: [`src-tauri/src/commands/mod.rs`](https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/mod.rs) (Commands), [`crates/supersearch-runtime/src/agent/executor.rs`](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/agent/executor.rs) (Executor), [`ui/scripts/bridge.js`](https://github.com/archdex-art/supersearch/blob/main/ui/scripts/bridge.js) (IPC bridge), [`crates/supersearch-runtime/src/kernel/mod.rs`](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/kernel/mod.rs) (Kernel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_app["UI app<br/>html/js UI<br/>[app.js]"]
  node_ui_search["Search UI<br/>search view<br/>[search.js]"]
  node_ui_agent["Agent UI<br/>intent UI<br/>[agent.js]"]
  node_ui_bridge["IPC bridge<br/>frontend bridge<br/>[bridge.js]"]
end

subgraph group_tauri["Tauri Host"]
  node_tauri_commands["Commands<br/>Tauri cmds<br/>[mod.rs]"]
  node_tauri_agent["Agent cmd<br/>native command<br/>[agent.rs]"]
  node_tauri_search["Search cmd<br/>native command<br/>[search.rs]"]
  node_tauri_ext["Extensions cmd<br/>native command<br/>[extensions.rs]"]
  node_tauri_journal["Journal cmd<br/>native command<br/>[journal.rs]"]
  node_tauri_state["App state<br/>host state<br/>[state.rs]"]
end

subgraph group_runtime["Runtime Kernel"]
  node_runtime_agent["Agent core<br/>runtime engine<br/>[mod.rs]"]
  node_patterns["Patterns<br/>intent classifier<br/>[patterns.rs]"]
  node_planner["Planner<br/>[planner.rs]"]
  node_executor["Executor<br/>task runner<br/>[executor.rs]"]
  node_capability{{"Capability gate<br/>security boundary<br/>[gate.rs]"}}
  node_journal[("Journal<br/>audit log<br/>[mod.rs]")]
  node_extensions["Extensions<br/>ext runtime<br/>[mod.rs]"]
  node_platform["Platform<br/>os abstraction<br/>[mod.rs]"]
  node_kernel["Kernel<br/>runtime core<br/>[mod.rs]"]
  node_reactive["Reactive<br/>future orchestration<br/>[mod.rs]"]
  node_scheduler["Scheduler<br/>future orchestration<br/>[mod.rs]"]
end

subgraph group_ops["Ops"]
  node_release["CI/CD<br/>build/release<br/>[release.yml]"]
end

node_ui_app -->|"events"| node_ui_bridge
node_ui_search -->|"search"| node_ui_bridge
node_ui_agent -->|"intent"| node_ui_bridge
node_ui_bridge -->|"IPC"| node_tauri_commands
node_tauri_commands -->|"agent"| node_tauri_agent
node_tauri_commands -->|"search"| node_tauri_search
node_tauri_commands -->|"extensions"| node_tauri_ext
node_tauri_commands -->|"journal"| node_tauri_journal
node_tauri_commands -->|"state"| node_tauri_state
node_tauri_agent -->|"invoke"| node_runtime_agent
node_tauri_search -->|"discover"| node_runtime_agent
node_runtime_agent -->|"classify"| node_patterns
node_patterns -->|"intent"| node_planner
node_planner -->|"task graph"| node_executor
node_executor -->|"authorize"| node_capability
node_executor -->|"os action"| node_platform
node_executor -->|"audit"| node_journal
node_extensions -->|"scope"| node_capability
node_extensions -->|"host"| node_platform
node_platform -->|"runtime"| node_kernel
node_kernel -.->|"future"| node_scheduler
node_kernel -.->|"future"| node_reactive
node_tauri_ext -->|"manage"| node_extensions
node_tauri_journal -->|"read"| node_journal
node_release -.->|"ship"| node_tauri_commands

click node_ui_app "https://github.com/archdex-art/supersearch/blob/main/ui/scripts/app.js"
click node_ui_search "https://github.com/archdex-art/supersearch/blob/main/ui/scripts/search.js"
click node_ui_agent "https://github.com/archdex-art/supersearch/blob/main/ui/scripts/agent.js"
click node_ui_bridge "https://github.com/archdex-art/supersearch/blob/main/ui/scripts/bridge.js"
click node_tauri_commands "https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/mod.rs"
click node_tauri_agent "https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/agent.rs"
click node_tauri_search "https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/search.rs"
click node_tauri_ext "https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/extensions.rs"
click node_tauri_journal "https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/journal.rs"
click node_tauri_state "https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/state.rs"
click node_runtime_agent "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/agent/mod.rs"
click node_patterns "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/agent/patterns.rs"
click node_planner "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/agent/planner.rs"
click node_executor "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/agent/executor.rs"
click node_capability "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/capability/gate.rs"
click node_journal "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/journal/mod.rs"
click node_extensions "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/extension/mod.rs"
click node_platform "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/platform/mod.rs"
click node_kernel "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/kernel/mod.rs"
click node_reactive "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/reactive/mod.rs"
click node_scheduler "https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/scheduler/mod.rs"
click node_release "https://github.com/archdex-art/supersearch/blob/main/.github/workflows/release.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_app,node_ui_search,node_ui_agent,node_ui_bridge toneBlue
class node_tauri_commands,node_tauri_agent,node_tauri_search,node_tauri_ext,node_tauri_journal,node_tauri_state toneAmber
class node_runtime_agent,node_patterns,node_planner,node_executor,node_capability,node_journal,node_extensions,node_platform,node_kernel,node_reactive,node_scheduler toneMint
class node_release toneRose
```

## Components

### Frontend

UI surfaces and browser-side logic

- [UI app](https://github.com/archdex-art/supersearch/blob/main/ui/scripts/app.js): html/js UI · Primary production command palette and settings UI · `ui/scripts/app.js`
- [Search UI](https://github.com/archdex-art/supersearch/blob/main/ui/scripts/search.js): search view · Search input, result ranking, and selection handling · `ui/scripts/search.js`
- [Agent UI](https://github.com/archdex-art/supersearch/blob/main/ui/scripts/agent.js): intent UI · Command parsing and execution entry from the palette · `ui/scripts/agent.js`
- [IPC bridge](https://github.com/archdex-art/supersearch/blob/main/ui/scripts/bridge.js): frontend bridge · Frontend messaging layer into the native backend · `ui/scripts/bridge.js`

### Tauri Host

Desktop app bridge and command surface

- [Commands](https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/mod.rs): Tauri cmds · Native command surface for search, agent, extensions, journal, settings, telemetry, updater, and window control · `src-tauri/src/commands/mod.rs`
- [Agent cmd](https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/agent.rs): native command · Entry point for intent execution requests · `src-tauri/src/commands/agent.rs`
- [Search cmd](https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/search.rs): native command · Search and system discovery entry points · `src-tauri/src/commands/search.rs`
- [Extensions cmd](https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/extensions.rs): native command · Extension management and execution surface · `src-tauri/src/commands/extensions.rs`
- [Journal cmd](https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/commands/journal.rs): native command · Audit and replay access from the host layer · `src-tauri/src/commands/journal.rs`
- [App state](https://github.com/archdex-art/supersearch/blob/main/src-tauri/src/state.rs): host state · Shared state, settings, and window lifecycle coordination · `src-tauri/src/state.rs`

### Runtime Kernel

Core intent, security, execution, and extensibility engine

- [Agent core](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/agent/mod.rs): runtime engine · Intent understanding, planning, and stepwise execution · `crates/supersearch-runtime/src/agent/mod.rs`
- [Patterns](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/agent/patterns.rs): intent classifier · Maps text into a closed intent set · `crates/supersearch-runtime/src/agent/patterns.rs`
- [Planner](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/agent/planner.rs): task planner · Converts intents into executable task graphs · `crates/supersearch-runtime/src/agent/planner.rs`
- [Executor](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/agent/executor.rs): task runner · Runs planned tasks against capability gates and OS actions · `crates/supersearch-runtime/src/agent/executor.rs`
- [Capability gate](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/capability/gate.rs): security boundary · Namespace and permission authorization before OS actions · `crates/supersearch-runtime/src/capability/gate.rs`
- [Journal](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/journal/mod.rs): audit log · Append-only execution record and replay trail · `crates/supersearch-runtime/src/journal/mod.rs`
- [Extensions](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/extension/mod.rs): ext runtime · Manifest-driven native and WASM extension hosting · `crates/supersearch-runtime/src/extension/mod.rs`
- [Platform](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/platform/mod.rs): os abstraction · Cross-platform process and automation boundary · `crates/supersearch-runtime/src/platform/mod.rs`
- [Kernel](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/kernel/mod.rs): runtime core · Process/runtime plumbing for the engine · `crates/supersearch-runtime/src/kernel/mod.rs`
- [Reactive](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/reactive/mod.rs): future orchestration · Signal graph and reconciliation layer not yet load-bearing · `crates/supersearch-runtime/src/reactive/mod.rs`
- [Scheduler](https://github.com/archdex-art/supersearch/blob/main/crates/supersearch-runtime/src/scheduler/mod.rs): future orchestration · Task scheduling and prioritization subsystem not yet central · `crates/supersearch-runtime/src/scheduler/mod.rs`

### Ops

Build, release, and deployment boundary

- [CI/CD](https://github.com/archdex-art/supersearch/blob/main/.github/workflows/release.yml): build/release · Automated build and release workflows · `.github/workflows/release.yml`

## Connections

- 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
