# carthadash/jarvis architecture

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

- Interactive diagram: https://gitdiagram.com/carthadash/jarvis
- Repository: https://github.com/carthadash/jarvis

## Overview

#### Purpose and entry points
This is a Tauri desktop knowledge-graph application with a React/Vite frontend, a Rust native backend, SQLite schema migrations, and a separate Node.js MCP server for programmatic graph access.

Frontend bootstraps at `src/main.tsx` and renders the application in `src/App.tsx`. Native startup is in `src-tauri/src/main.rs` and `src-tauri/src/lib.rs`. The MCP process starts from `mcp-server/index.js`.

#### Frontend application shell
The React UI is organized around graph navigation, node editing, inbox processing, ingestion, and settings. Core screen composition and global interaction likely originate in:
- `src/App.tsx`
- `src/components/Sidebar.tsx`
- `src/components/TopBar.tsx`

The UI boundary is the browser/webview layer; it delegates persistent operations to the native Tauri backend through database-oriented hooks such as `src/hooks/useDatabase.ts`.

#### Graph visualization and interaction
Graph exploration is a primary feature, represented by dedicated graph, canvas, filtering, and local-context components:
- `src/components/Graph.tsx`
- `src/components/GraphCanvas.tsx`
- `src/components/MiniGraph.tsx`

Graph behavior is separated from rendering through `src/hooks/useGraph.ts`, while force-layout mechanics and shared graph parameters reside in `src/lib/forceSim.ts` and `src/lib/graphConstants.ts`. This establishes a flow from persisted nodes/connections → graph hook/layout → interactive canvas and filters.

#### Node lifecycle and knowledge capture
Nodes appear to support creation, editing, tags, connections, history, search, and fast capture. The main editing and capture boundary is represented by:
- `src/components/NodeEditor.tsx`
- `src/components/QuickAdd.tsx`
- `src/components/ProcessInbox.tsx`

`src/components/IngestWizard.tsx` provides a more structured ingestion path, while `src/components/NodeHistory.tsx` exposes revision/history data. Rich-text features are implemented with Tiptap extensions under `src/lib/tiptapExtensions`, including node mentions and pasted images.

#### Native backend and persistence
Rust implements the authoritative application backend: Tauri commands, configuration, domain models, persistence, markdown processing, image handling, and index output:
- `src-tauri/src/commands.rs`
- `src-tauri/src/db.rs`
- `src-tauri/src/models.rs`

The persistent schema evolves through SQLite migrations in `src-tauri/migrations/0001_init.sql` through `src-tauri/migrations/0005_node_history.sql`. Schema stages explicitly cover initial data, tags, a v2 schema, daily logs, and node history. Backend error handling, configuration, and generated index writing are isolated in `src-tauri/src/error.rs`, `src-tauri/src/config.rs`, and `src-tauri/src/index_writer.rs`.

#### MCP integration boundary
`mcp-server/` is an independent Node.js service exposing graph/database capabilities as tools for an MCP client or agent. Its database adapter is `mcp-server/db.js`; tool registration/orchestration is `mcp-server/index.js`.

The tool surface maps directly to core knowledge-graph operations: node CRUD (`mcp-server/tools/createNode.js`, `mcp-server/tools/updateNode.js`), relationship mutation (`mcp-server/tools/addConnection.js`, `mcp-server/tools/removeConnection.js`), retrieval/search (`mcp-server/tools/searchNodes.js`, `mcp-server/tools/getBacklinks.js`), and activity logging (`mcp-server/tools/appendLog.js`, `mcp-server/tools/sessionLog.js`). HTML content can be normalized through `mcp-server/lib/htmlToMarkdown.js`.

#### Runtime and infrastructure boundaries
The frontend runs as a Vite-built TypeScript/React webview; the desktop host is Tauri/Rust, configured by `src-tauri/tauri.conf.json` with permissions in `src-tauri/capabilities/default.json`. Native storage is migration-managed SQLite. The MCP server is a separate Node.js runtime with its own `mcp-server/package.json`, forming an automation/API boundary rather than part of the desktop UI process.

Main entry points: [`src/App.tsx`](https://github.com/carthadash/jarvis/blob/main/src/App.tsx) (Application shell), [`src-tauri/src/commands.rs`](https://github.com/carthadash/jarvis/blob/main/src-tauri/src/commands.rs) (Tauri commands), [`mcp-server/tools/createNode.js`](https://github.com/carthadash/jarvis/blob/main/mcp-server/tools/createNode.js) (Graph operation tools), [`src/hooks/useDatabase.ts`](https://github.com/carthadash/jarvis/blob/main/src/hooks/useDatabase.ts) (Database bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Webview"]
  node_frontend_entry["Frontend bootstrap<br/>React entry<br/>[main.tsx]"]
  node_app_shell["Application shell<br/>React UI<br/>[App.tsx]"]
  node_navigation["Navigation chrome<br/>React components<br/>[Sidebar.tsx]"]
  node_graph_ui["Graph explorer<br/>React components<br/>[Graph.tsx]"]
  node_graph_state["Graph behavior &amp; layout<br/>React hook / simulation<br/>[useGraph.ts]"]
  node_capture_ui["Capture &amp; node lifecycle<br/>React components<br/>[NodeEditor.tsx]"]
  node_database_hook["Database bridge<br/>Tauri hook<br/>[useDatabase.ts]"]
end

subgraph group_native["Tauri Native Backend"]
  node_tauri_entry["Native startup<br/>Rust entry<br/>[main.rs]"]
  node_commands["Tauri commands<br/>Rust command API<br/>[commands.rs]"]
  node_domain_backend["Domain &amp; content services<br/>Rust services<br/>[models.rs]"]
  node_persistence[("SQLite persistence<br/>Rust database layer<br/>[db.rs]")]
end

subgraph group_storage["SQLite Storage"]
  node_migrations["Schema migrations<br/>SQLite migrations<br/>[0001_init.sql]"]
  node_sqlite[("Knowledge graph database<br/>SQLite database")]
end

subgraph group_mcp["MCP Server"]
  node_mcp_entry["MCP tool server<br/>Node.js MCP service<br/>[index.js]"]
  node_mcp_tools["Graph operation tools<br/>MCP tools<br/>[createNode.js]"]
  node_mcp_db[("Database adapter<br/>Node.js persistence adapter<br/>[db.js]")]
  node_mcp_content["HTML normalization<br/>Node.js content utility<br/>[htmlToMarkdown.js]"]
end

node_frontend_entry -->|"renders"| node_app_shell
node_app_shell -->|"composes"| node_navigation
node_app_shell -->|"hosts"| node_graph_ui
node_app_shell -->|"hosts"| node_capture_ui
node_graph_ui -->|"uses"| node_graph_state
node_graph_state -->|"loads graph data"| node_database_hook
node_capture_ui -->|"persists changes"| node_database_hook
node_database_hook -->|"invokes"| node_commands
node_tauri_entry -->|"hosts"| node_commands
node_commands -->|"uses"| node_domain_backend
node_commands -->|"reads and writes"| node_persistence
node_persistence -->|"stores"| node_sqlite
node_migrations -->|"evolves schema"| node_sqlite
node_mcp_entry -->|"registers"| node_mcp_tools
node_mcp_tools -.->|"normalizes content"| node_mcp_content
node_mcp_tools -->|"uses"| node_mcp_db
node_mcp_db -->|"accesses"| node_sqlite

click node_frontend_entry "https://github.com/carthadash/jarvis/blob/main/src/main.tsx"
click node_app_shell "https://github.com/carthadash/jarvis/blob/main/src/App.tsx"
click node_navigation "https://github.com/carthadash/jarvis/blob/main/src/components/Sidebar.tsx"
click node_graph_ui "https://github.com/carthadash/jarvis/blob/main/src/components/Graph.tsx"
click node_graph_state "https://github.com/carthadash/jarvis/blob/main/src/hooks/useGraph.ts"
click node_capture_ui "https://github.com/carthadash/jarvis/blob/main/src/components/NodeEditor.tsx"
click node_database_hook "https://github.com/carthadash/jarvis/blob/main/src/hooks/useDatabase.ts"
click node_tauri_entry "https://github.com/carthadash/jarvis/blob/main/src-tauri/src/main.rs"
click node_commands "https://github.com/carthadash/jarvis/blob/main/src-tauri/src/commands.rs"
click node_domain_backend "https://github.com/carthadash/jarvis/blob/main/src-tauri/src/models.rs"
click node_persistence "https://github.com/carthadash/jarvis/blob/main/src-tauri/src/db.rs"
click node_migrations "https://github.com/carthadash/jarvis/blob/main/src-tauri/migrations/0001_init.sql"
click node_mcp_entry "https://github.com/carthadash/jarvis/blob/main/mcp-server/index.js"
click node_mcp_tools "https://github.com/carthadash/jarvis/blob/main/mcp-server/tools/createNode.js"
click node_mcp_db "https://github.com/carthadash/jarvis/blob/main/mcp-server/db.js"
click node_mcp_content "https://github.com/carthadash/jarvis/blob/main/mcp-server/lib/htmlToMarkdown.js"

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_frontend_entry,node_app_shell,node_navigation,node_graph_ui,node_graph_state,node_capture_ui,node_database_hook toneBlue
class node_tauri_entry,node_commands,node_domain_backend,node_persistence toneAmber
class node_migrations,node_sqlite toneMint
class node_mcp_entry,node_mcp_tools,node_mcp_db,node_mcp_content toneRose
```

## Components

### React Webview

Vite-built desktop UI.

- [Frontend bootstrap](https://github.com/carthadash/jarvis/blob/main/src/main.tsx): React entry · `src/main.tsx`
- [Application shell](https://github.com/carthadash/jarvis/blob/main/src/App.tsx): React UI · Composes navigation and global application interactions. · `src/App.tsx`
- [Navigation chrome](https://github.com/carthadash/jarvis/blob/main/src/components/Sidebar.tsx): React components · Sidebar and top-bar navigation. · `src/components/Sidebar.tsx`
- [Graph explorer](https://github.com/carthadash/jarvis/blob/main/src/components/Graph.tsx): React components · Interactive graph canvas and local graph views. · `src/components/Graph.tsx`
- [Graph behavior & layout](https://github.com/carthadash/jarvis/blob/main/src/hooks/useGraph.ts): React hook / simulation · Separates graph state and force layout from rendering. · `src/hooks/useGraph.ts`
- [Capture & node lifecycle](https://github.com/carthadash/jarvis/blob/main/src/components/NodeEditor.tsx): React components · Editing, quick capture, inbox processing, and ingestion. · `src/components/NodeEditor.tsx`
- [Database bridge](https://github.com/carthadash/jarvis/blob/main/src/hooks/useDatabase.ts): Tauri hook · Webview boundary for persistent operations. · `src/hooks/useDatabase.ts`

### Tauri Native Backend

Authoritative desktop application backend.

- [Native startup](https://github.com/carthadash/jarvis/blob/main/src-tauri/src/main.rs): Rust entry · Launches the Tauri desktop host. · `src-tauri/src/main.rs`
- [Tauri commands](https://github.com/carthadash/jarvis/blob/main/src-tauri/src/commands.rs): Rust command API · Native operations exposed to the webview. · `src-tauri/src/commands.rs`
- [Domain & content services](https://github.com/carthadash/jarvis/blob/main/src-tauri/src/models.rs): Rust services · Models, markdown, images, configuration, and index output. · `src-tauri/src/models.rs`
- [SQLite persistence](https://github.com/carthadash/jarvis/blob/main/src-tauri/src/db.rs): Rust database layer · Authoritative reads and writes for graph data. · `src-tauri/src/db.rs`

### SQLite Storage

Migration-managed knowledge graph data.

- [Schema migrations](https://github.com/carthadash/jarvis/blob/main/src-tauri/migrations/0001_init.sql): SQLite migrations · Initial schema through tags, v2, daily logs, and node history. · `src-tauri/migrations/0001_init.sql`
- **Knowledge graph database**: SQLite database · Nodes, relationships, tags, logs, and history.

### MCP Server

Independent Node.js automation boundary.

- [MCP tool server](https://github.com/carthadash/jarvis/blob/main/mcp-server/index.js): Node.js MCP service · Registers graph operations for MCP clients and agents. · `mcp-server/index.js`
- [Graph operation tools](https://github.com/carthadash/jarvis/blob/main/mcp-server/tools/createNode.js): MCP tools · CRUD, connections, search, backlinks, and activity logging. · `mcp-server/tools/createNode.js`
- [Database adapter](https://github.com/carthadash/jarvis/blob/main/mcp-server/db.js): Node.js persistence adapter · Connects MCP tools to the shared graph database. · `mcp-server/db.js`
- [HTML normalization](https://github.com/carthadash/jarvis/blob/main/mcp-server/lib/htmlToMarkdown.js): Node.js content utility · Converts HTML content to Markdown. · `mcp-server/lib/htmlToMarkdown.js`

## Connections

- Frontend bootstrap → Application shell: renders
- Application shell → Navigation chrome: composes
- Application shell → Graph explorer: hosts
- Application shell → Capture & node lifecycle: hosts
- Graph explorer → Graph behavior & layout: uses
- Graph behavior & layout → Database bridge: loads graph data
- Capture & node lifecycle → Database bridge: persists changes
- Database bridge → Tauri commands: invokes
- Native startup → Tauri commands: hosts
- Tauri commands → Domain & content services: uses
- Tauri commands → SQLite persistence: reads and writes
- SQLite persistence → Knowledge graph database: stores
- Schema migrations → Knowledge graph database: evolves schema
- MCP tool server → Graph operation tools: registers
- Graph operation tools → HTML normalization: normalizes content
- Graph operation tools → Database adapter: uses
- Database adapter → Knowledge graph database: accesses · Shares the native knowledge graph store.