# marvis-ai/marvis architecture

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

- Interactive diagram: https://gitdiagram.com/marvis-ai/marvis
- Repository: https://github.com/marvis-ai/marvis

## Overview

Marvis is a privacy-first desktop AI assistant: users ask through an always-on-top bar, optionally attach a recent screen frame, and receive streamed provider responses; or start meeting capture and view live transcripts and rolling summaries. React views invoke the Rust core, which owns sensitive capture, audio, model access, keys, and local persistence. The README also documents onboarding, permissions, hotkeys, deep links, and provider failover. Relationships for unsampled subsystems below are limited to documented workflows; source-level evidence is cited where available.

Main entry points: [`apps/native/src-tauri/src/ask.rs`](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/ask.rs) (Ask orchestration), [`apps/native/src-tauri/src/listen.rs`](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/listen.rs) (Listen orchestration), [`apps/native/src/views/Bar.tsx`](https://github.com/marvis-ai/marvis/blob/master/apps/native/src/views/Bar.tsx) (Overlay bar), [`apps/native/src/lib/commands.ts`](https://github.com/marvis-ai/marvis/blob/master/apps/native/src/lib/commands.ts) (Command bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_bar["Overlay bar<br/>[Bar.tsx]"]
  node_chat["Ask and chat<br/>[ChatSection.tsx]"]
  node_listen_ui["Listen card<br/>[ListenSection.tsx]"]
  node_prefs["Settings and setup<br/>[Onboarding.tsx]"]
  node_commands["Command bridge<br/>[commands.ts]"]
end

subgraph group_core["Assistant core"]
  node_ask["Ask orchestration<br/>[ask.rs]"]
  node_capture["Screen capture<br/>[controller.rs]"]
  node_llm["LLM providers<br/>[mod.rs]"]
  node_config["Provider configuration<br/>[config.rs]"]
  node_keystore["Local API keys<br/>[keystore.rs]"]
  node_storage[("Session database<br/>[storage.rs]")]
end

subgraph group_meeting["Meeting intelligence"]
  node_audio["Audio capture<br/>[recorder.rs]"]
  node_listen["Listen orchestration<br/>[listen.rs]"]
  node_stt["Speech recognition<br/>[mod.rs]"]
  node_summaries["Meeting summaries<br/>[listen.rs]"]
end

subgraph group_platform["Platform and setup"]
  node_windows["Overlay windows<br/>[mod.rs]"]
  node_permissions["Permission gates<br/>[mod.rs]"]
  node_hotkeys["Global hotkey<br/>[hotkey.rs]"]
  node_deeplinks["Deep links<br/>[deeplink.rs]"]
end

node_user(("Desktop user"))

node_user -->|"asks through"| node_bar
node_bar -->|"invokes commands"| node_commands
node_commands -->|"starts Ask"| node_ask
node_ask -->|"reads recent frame"| node_capture
node_ask -->|"streams request"| node_llm
node_ask -->|"persists conversation"| node_storage
node_llm -->|"uses providers"| node_config
node_config -.->|"uses API keys"| node_keystore
node_user -->|"starts listening"| node_listen_ui
node_listen_ui -->|"invokes commands"| node_commands
node_listen -->|"captures channels"| node_audio
node_listen -->|"transcribes audio"| node_stt
node_listen -->|"stores transcript"| node_storage
node_listen -->|"creates summaries"| node_summaries
node_summaries -.->|"requests summaries"| node_llm
node_user -->|"configures app"| node_prefs
node_prefs -->|"invokes commands"| node_commands
node_windows -->|"hosts view"| node_bar
node_permissions -->|"gates access"| node_bar
node_hotkeys -.->|"surfaces bar"| node_windows
node_deeplinks -->|"fires Ask"| node_ask

click node_bar "https://github.com/marvis-ai/marvis/blob/master/apps/native/src/views/Bar.tsx"
click node_chat "https://github.com/marvis-ai/marvis/blob/master/apps/native/src/components/ChatSection.tsx"
click node_listen_ui "https://github.com/marvis-ai/marvis/blob/master/apps/native/src/components/ListenSection.tsx"
click node_prefs "https://github.com/marvis-ai/marvis/blob/master/apps/native/src/components/prefs/Onboarding.tsx"
click node_commands "https://github.com/marvis-ai/marvis/blob/master/apps/native/src/lib/commands.ts"
click node_ask "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/ask.rs"
click node_capture "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/capture/controller.rs"
click node_llm "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/llm/mod.rs"
click node_config "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/config.rs"
click node_keystore "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/keystore.rs"
click node_storage "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/storage.rs"
click node_audio "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/audio/recorder.rs"
click node_listen "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/listen.rs"
click node_stt "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/stt/mod.rs"
click node_summaries "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/listen.rs"
click node_windows "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/windows/mod.rs"
click node_permissions "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/permissions/mod.rs"
click node_hotkeys "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/hotkey.rs"
click node_deeplinks "https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/deeplink.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_bar,node_chat,node_listen_ui,node_prefs,node_commands,node_user toneBlue
class node_ask,node_capture,node_llm,node_config,node_keystore,node_storage toneAmber
class node_audio,node_listen,node_stt,node_summaries toneMint
class node_windows,node_permissions,node_hotkeys,node_deeplinks toneRose
```

## Components

### Desktop interface

- [Overlay bar](https://github.com/marvis-ai/marvis/blob/master/apps/native/src/views/Bar.tsx): `apps/native/src/views/Bar.tsx`
- [Ask and chat](https://github.com/marvis-ai/marvis/blob/master/apps/native/src/components/ChatSection.tsx): `apps/native/src/components/ChatSection.tsx`
- [Listen card](https://github.com/marvis-ai/marvis/blob/master/apps/native/src/components/ListenSection.tsx): `apps/native/src/components/ListenSection.tsx`
- [Settings and setup](https://github.com/marvis-ai/marvis/blob/master/apps/native/src/components/prefs/Onboarding.tsx): `apps/native/src/components/prefs/Onboarding.tsx`
- [Command bridge](https://github.com/marvis-ai/marvis/blob/master/apps/native/src/lib/commands.ts): `apps/native/src/lib/commands.ts`

### Assistant core

- [Ask orchestration](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/ask.rs): `apps/native/src-tauri/src/ask.rs`
- [Screen capture](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/capture/controller.rs): `apps/native/src-tauri/src/capture/controller.rs`
- [LLM providers](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/llm/mod.rs): `apps/native/src-tauri/src/llm/mod.rs`
- [Provider configuration](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/config.rs): `apps/native/src-tauri/src/config.rs`
- [Local API keys](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/keystore.rs): `apps/native/src-tauri/src/keystore.rs`
- [Session database](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/storage.rs): `apps/native/src-tauri/src/storage.rs`

### Meeting intelligence

- [Audio capture](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/audio/recorder.rs): `apps/native/src-tauri/src/audio/recorder.rs`
- [Listen orchestration](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/listen.rs): `apps/native/src-tauri/src/listen.rs`
- [Speech recognition](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/stt/mod.rs): `apps/native/src-tauri/src/stt/mod.rs`
- [Meeting summaries](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/listen.rs): `apps/native/src-tauri/src/listen.rs`

### Platform and setup

- [Overlay windows](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/windows/mod.rs): `apps/native/src-tauri/src/windows/mod.rs`
- [Permission gates](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/permissions/mod.rs): `apps/native/src-tauri/src/permissions/mod.rs`
- [Global hotkey](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/hotkey.rs): `apps/native/src-tauri/src/hotkey.rs`
- [Deep links](https://github.com/marvis-ai/marvis/blob/master/apps/native/src-tauri/src/deeplink.rs): `apps/native/src-tauri/src/deeplink.rs`

### Other components

- **Desktop user**

## Connections

- Desktop user → Overlay bar: asks through (evidence: `README.md`)
- Overlay bar → Command bridge: invokes commands (evidence: `README.md`)
- Command bridge → Ask orchestration: starts Ask (evidence: `apps/native/src/lib/commands.ts`)
- Ask orchestration → Screen capture: reads recent frame (evidence: `README.md`)
- Ask orchestration → LLM providers: streams request (evidence: `README.md`)
- Ask orchestration → Session database: persists conversation (evidence: `README.md`)
- LLM providers → Provider configuration: uses providers (evidence: `apps/native/src-tauri/src/config.rs`)
- Provider configuration → Local API keys: uses API keys
- Desktop user → Listen card: starts listening (evidence: `README.md`)
- Listen card → Command bridge: invokes commands (evidence: `README.md`)
- Listen orchestration → Audio capture: captures channels (evidence: `README.md`)
- Listen orchestration → Speech recognition: transcribes audio (evidence: `README.md`)
- Listen orchestration → Session database: stores transcript (evidence: `README.md`)
- Listen orchestration → Meeting summaries: creates summaries (evidence: `README.md`)
- Meeting summaries → LLM providers: requests summaries
- Desktop user → Settings and setup: configures app (evidence: `README.md`)
- Settings and setup → Command bridge: invokes commands (evidence: `README.md`)
- Overlay windows → Overlay bar: hosts view (evidence: `apps/native/src-tauri/src/windows/mod.rs`)
- Permission gates → Overlay bar: gates access (evidence: `README.md`)
- Global hotkey → Overlay windows: surfaces bar
- Deep links → Ask orchestration: fires Ask (evidence: `README.md`)
