# ace-haxxed/nova-arch architecture

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

- Interactive diagram: https://gitdiagram.com/ace-haxxed/nova-arch
- Repository: https://github.com/ace-haxxed/nova-arch
- Video tour (about a minute): https://gitdiagram.com/ace-haxxed/nova-arch/video

## Overview

NOVA is a desktop AI assistant that turns text or voice requests into model-directed tool actions. The primary workflow runs from the conversation UI through the agent loop, model streaming, tool selection and desktop command wrappers, then returns results for the next agent turn and logs actions. Major capabilities include screen and input control, files and browser tasks, voice and wake-word support, settings/onboarding, and local memory. Rust provides the desktop command and Linux platform layer. Some feature wiring is documented only in the README; the graph avoids asserting unsampled call paths.

Main entry points: [`src/core/agent.ts`](https://github.com/ace-haxxed/nova-arch/blob/main/src/core/agent.ts) (Agent loop), [`src/platform/desktop.ts`](https://github.com/ace-haxxed/nova-arch/blob/main/src/platform/desktop.ts) (Desktop tools), [`src/hooks/useAgent.ts`](https://github.com/ace-haxxed/nova-arch/blob/main/src/hooks/useAgent.ts) (Agent interface), [`src-tauri/src/platform/mod.rs`](https://github.com/ace-haxxed/nova-arch/blob/main/src-tauri/src/platform/mod.rs) (Linux dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_app["App shell<br/>[App.tsx]"]
  node_conversation_ui["Conversation UI<br/>[DesktopLayout.tsx]"]
  node_settings_ui["Settings and onboarding<br/>[SettingsPanel.tsx]"]
  node_voice["Voice and wake word<br/>[useVoice.ts]"]
  node_agent_hook["Agent interface<br/>[useAgent.ts]"]
end

subgraph group_agent["Agent and models"]
  node_conversation_store[("Conversation state<br/>[conversation.ts]")]
  node_agent_loop["Agent loop<br/>[agent.ts]"]
  node_context["Context assembly<br/>[context.ts]"]
  node_memory[("Conversation and memory<br/>[memory.ts]")]
  node_llm["Model providers<br/>[llm.ts]"]
  node_provider_transport["Provider transport<br/>[llmTransport.ts]"]
  node_tool_router["Tool selection<br/>[index.ts]"]
end

subgraph group_capabilities["Desktop capabilities"]
  node_tool_wrappers["Desktop tools<br/>[desktop.ts]"]
  node_vision_tools["Vision tools<br/>[vision.ts]"]
  node_web_tools["Web and timers<br/>[web.ts]"]
  node_tauri_commands["Desktop commands"]
end

subgraph group_platform["Linux platform and state"]
  node_linux_dispatch["Linux dispatch<br/>[mod.rs]"]
  node_platform_detect["Session detection<br/>[detect.rs]"]
  node_local_state[("App state<br/>[state.rs]")]
end

node_user(("User"))
node_external_model{{"Model backend"}}
node_os{{"Linux desktop"}}

node_user -->|"requests"| node_conversation_ui
node_app -->|"renders"| node_conversation_ui
node_app -->|"opens"| node_settings_ui
node_conversation_ui -->|"submits"| node_agent_hook
node_agent_hook -->|"runs"| node_agent_loop
node_agent_hook -->|"updates"| node_conversation_store
node_conversation_store -->|"loads and saves"| node_memory
node_agent_loop -->|"recalls and trims"| node_memory
node_agent_loop -->|"assembles context"| node_context
node_agent_loop -->|"requests completion"| node_llm
node_llm -->|"streams through"| node_provider_transport
node_provider_transport -.->|"sends requests"| node_external_model
node_agent_loop -->|"gets tools"| node_tool_router
node_tool_router -->|"dispatches to"| node_tool_wrappers
node_tool_wrappers -->|"invokes"| node_tauri_commands
node_tool_wrappers -->|"includes"| node_vision_tools
node_tool_wrappers -->|"includes"| node_web_tools
node_tauri_commands -.->|"uses platform helpers"| node_linux_dispatch
node_linux_dispatch -->|"selects session path"| node_platform_detect
node_linux_dispatch -->|"controls desktop"| node_os
node_voice -->|"captures microphone"| node_tauri_commands
node_settings_ui -.->|"configures"| node_local_state

click node_app "https://github.com/ace-haxxed/nova-arch/blob/main/src/App.tsx"
click node_conversation_ui "https://github.com/ace-haxxed/nova-arch/blob/main/src/components/desktop/DesktopLayout.tsx"
click node_settings_ui "https://github.com/ace-haxxed/nova-arch/blob/main/src/components/Settings/SettingsPanel.tsx"
click node_voice "https://github.com/ace-haxxed/nova-arch/blob/main/src/hooks/useVoice.ts"
click node_agent_hook "https://github.com/ace-haxxed/nova-arch/blob/main/src/hooks/useAgent.ts"
click node_conversation_store "https://github.com/ace-haxxed/nova-arch/blob/main/src/store/conversation.ts"
click node_agent_loop "https://github.com/ace-haxxed/nova-arch/blob/main/src/core/agent.ts"
click node_context "https://github.com/ace-haxxed/nova-arch/blob/main/src/core/context.ts"
click node_memory "https://github.com/ace-haxxed/nova-arch/blob/main/src/core/memory.ts"
click node_llm "https://github.com/ace-haxxed/nova-arch/blob/main/src/core/llm.ts"
click node_provider_transport "https://github.com/ace-haxxed/nova-arch/blob/main/src/lib/llmTransport.ts"
click node_tool_router "https://github.com/ace-haxxed/nova-arch/blob/main/src/platform/index.ts"
click node_tool_wrappers "https://github.com/ace-haxxed/nova-arch/blob/main/src/platform/desktop.ts"
click node_vision_tools "https://github.com/ace-haxxed/nova-arch/blob/main/src/core/tools/vision.ts"
click node_web_tools "https://github.com/ace-haxxed/nova-arch/blob/main/src/core/tools/web.ts"
click node_tauri_commands "https://github.com/ace-haxxed/nova-arch/tree/main/src-tauri/src/commands"
click node_linux_dispatch "https://github.com/ace-haxxed/nova-arch/blob/main/src-tauri/src/platform/mod.rs"
click node_platform_detect "https://github.com/ace-haxxed/nova-arch/blob/main/src-tauri/src/platform/detect.rs"
click node_local_state "https://github.com/ace-haxxed/nova-arch/blob/main/src-tauri/src/state.rs"

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_app,node_conversation_ui,node_settings_ui,node_voice,node_agent_hook,node_user toneBlue
class node_conversation_store,node_agent_loop,node_context,node_memory,node_llm,node_provider_transport,node_tool_router toneAmber
class node_tool_wrappers,node_vision_tools,node_web_tools,node_tauri_commands toneMint
class node_linux_dispatch,node_platform_detect,node_local_state toneRose
class node_external_model,node_os toneIndigo
```

## Components

### User interaction

- [App shell](https://github.com/ace-haxxed/nova-arch/blob/main/src/App.tsx): `src/App.tsx`
- [Conversation UI](https://github.com/ace-haxxed/nova-arch/blob/main/src/components/desktop/DesktopLayout.tsx): `src/components/desktop/DesktopLayout.tsx`
- [Settings and onboarding](https://github.com/ace-haxxed/nova-arch/blob/main/src/components/Settings/SettingsPanel.tsx): `src/components/Settings/SettingsPanel.tsx`
- [Voice and wake word](https://github.com/ace-haxxed/nova-arch/blob/main/src/hooks/useVoice.ts): `src/hooks/useVoice.ts`
- [Agent interface](https://github.com/ace-haxxed/nova-arch/blob/main/src/hooks/useAgent.ts): `src/hooks/useAgent.ts`

### Agent and models

- [Conversation state](https://github.com/ace-haxxed/nova-arch/blob/main/src/store/conversation.ts): `src/store/conversation.ts`
- [Agent loop](https://github.com/ace-haxxed/nova-arch/blob/main/src/core/agent.ts): `src/core/agent.ts`
- [Context assembly](https://github.com/ace-haxxed/nova-arch/blob/main/src/core/context.ts): `src/core/context.ts`
- [Conversation and memory](https://github.com/ace-haxxed/nova-arch/blob/main/src/core/memory.ts): `src/core/memory.ts`
- [Model providers](https://github.com/ace-haxxed/nova-arch/blob/main/src/core/llm.ts): `src/core/llm.ts`
- [Provider transport](https://github.com/ace-haxxed/nova-arch/blob/main/src/lib/llmTransport.ts): `src/lib/llmTransport.ts`
- [Tool selection](https://github.com/ace-haxxed/nova-arch/blob/main/src/platform/index.ts): `src/platform/index.ts`

### Desktop capabilities

- [Desktop tools](https://github.com/ace-haxxed/nova-arch/blob/main/src/platform/desktop.ts): `src/platform/desktop.ts`
- [Vision tools](https://github.com/ace-haxxed/nova-arch/blob/main/src/core/tools/vision.ts): `src/core/tools/vision.ts`
- [Web and timers](https://github.com/ace-haxxed/nova-arch/blob/main/src/core/tools/web.ts): `src/core/tools/web.ts`
- [Desktop commands](https://github.com/ace-haxxed/nova-arch/tree/main/src-tauri/src/commands): `src-tauri/src/commands`

### Linux platform and state

- [Linux dispatch](https://github.com/ace-haxxed/nova-arch/blob/main/src-tauri/src/platform/mod.rs): `src-tauri/src/platform/mod.rs`
- [Session detection](https://github.com/ace-haxxed/nova-arch/blob/main/src-tauri/src/platform/detect.rs): `src-tauri/src/platform/detect.rs`
- [App state](https://github.com/ace-haxxed/nova-arch/blob/main/src-tauri/src/state.rs): `src-tauri/src/state.rs`

### Other components

- **User**
- **Model backend**
- **Linux desktop**

## Connections

- User → Conversation UI: requests (evidence: `README.md`)
- App shell → Conversation UI: renders (evidence: `src/App.tsx`)
- App shell → Settings and onboarding: opens (evidence: `src/App.tsx`)
- Conversation UI → Agent interface: submits (evidence: `src/hooks/useAgent.ts`)
- Agent interface → Agent loop: runs (evidence: `src/hooks/useAgent.ts`)
- Agent interface → Conversation state: updates (evidence: `src/hooks/useAgent.ts`)
- Conversation state → Conversation and memory: loads and saves (evidence: `src/store/conversation.ts`)
- Agent loop → Conversation and memory: recalls and trims (evidence: `src/core/agent.ts`)
- Agent loop → Context assembly: assembles context (evidence: `src/core/context.ts`)
- Agent loop → Model providers: requests completion (evidence: `src/core/agent.ts`)
- Model providers → Provider transport: streams through (evidence: `src/core/llm.ts`)
- Provider transport → Model backend: sends requests
- Agent loop → Tool selection: gets tools (evidence: `src/core/agent.ts`)
- Tool selection → Desktop tools: dispatches to (evidence: `src/platform/index.ts`)
- Desktop tools → Desktop commands: invokes (evidence: `README.md`)
- Desktop tools → Vision tools: includes (evidence: `src/platform/desktop.ts`)
- Desktop tools → Web and timers: includes (evidence: `src/platform/desktop.ts`)
- Desktop commands → Linux dispatch: uses platform helpers (evidence: `src-tauri/src/commands/apps.rs`)
- Linux dispatch → Session detection: selects session path (evidence: `README.md`)
- Linux dispatch → Linux desktop: controls desktop (evidence: `README.md`)
- Voice and wake word → Desktop commands: captures microphone (evidence: `README.md`)
- Settings and onboarding → App state: configures