# sheng-tse/jupynvim architecture

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

- Interactive diagram: https://gitdiagram.com/sheng-tse/jupynvim
- Repository: https://github.com/sheng-tse/jupynvim

## Overview

jupynvim is a Neovim notebook editor backed by a Rust service. The main workflow opens and edits an .ipynb, starts a selected or inferred Jupyter kernel, executes cells, routes results back into notebook state, and renders them in the editor. Lua modules also provide notebook-aware LSP, kernel completion/inspection, and Kitty graphics; remote mode extends the backend with SSH-connected files, terminals, and search. The tree and excerpts support the runtime entry points and several backend paths; unsampled Lua/backend wiring is shown only where README capabilities establish it.

Main entry points: [`core/src/rpc/mod.rs`](https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/mod.rs) (RPC server), [`lua/jupynvim/notebook/init.lua`](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/init.lua) (Notebook editing), [`core/src/rpc/exec.rs`](https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/exec.rs) (Execution RPCs), [`lua/jupynvim/notebook/render.lua`](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/render.lua) (Cell rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Neovim editor"]
  node_lua_init["Plugin setup<br/>[init.lua]"]
  node_nb_ui["Notebook editing<br/>[init.lua]"]
  node_render["Cell rendering<br/>[render.lua]"]
  node_markdown["Markdown cells<br/>[markdown.lua]"]
  node_images["Image display<br/>[image.lua]"]
  node_lua_lsp["Notebook LSP<br/>[init.lua]"]
  node_kernel_lsp["Kernel LSP proxy<br/>[kernel.lua]"]
  node_kitty["Kitty graphics<br/>[kitty.rs]"]
end

subgraph group_notebook["Notebook runtime"]
  node_backend_connect["Backend connection<br/>[connect.lua]"]
  node_rpc_lua["Lua RPC client<br/>[rpc.lua]"]
  node_core["RPC server<br/>[mod.rs]"]
  node_notebook_io["Notebook format<br/>[notebook.rs]"]
  node_session["Notebook session<br/>[session.rs]"]
end

subgraph group_kernel["Kernel services"]
  node_kernel_rpc["Execution RPCs<br/>[exec.rs]"]
  node_kernelspec["Kernel discovery<br/>[kernelspec.rs]"]
  node_kernel_wire["Jupyter protocol<br/>[kernel.rs]"]
end

subgraph group_remote["Remote workspace"]
  node_remote_ui["Remote workspace UI<br/>[dashboard.lua]"]
  node_remote_files["Remote files<br/>[fs.rs]"]
  node_remote_proc["Remote terminals<br/>[proc.rs]"]
  node_remote_search["Remote search<br/>[search.rs]"]
end

node_user(("Notebook user"))
node_jupyter_kernel(("Jupyter kernel"))
node_ssh_host(("SSH host"))
node_lsp_server(("Language server"))
node_terminal(("Graphics terminal"))

node_user -->|"opens notebook"| node_lua_init
node_lua_init -->|"sets up"| node_nb_ui
node_nb_ui -->|"connects backend"| node_backend_connect
node_backend_connect -->|"uses RPC"| node_rpc_lua
node_rpc_lua -->|"sends messages"| node_core
node_core -->|"reads and writes"| node_notebook_io
node_core -->|"dispatches"| node_kernel_rpc
node_kernel_rpc -->|"selects kernel"| node_kernelspec
node_kernel_rpc -->|"manages session"| node_session
node_kernel_rpc -->|"executes code"| node_kernel_wire
node_kernel_wire -->|"Jupyter messages"| node_jupyter_kernel
node_kernel_wire -->|"streams events"| node_session
node_session -->|"returns notebook state"| node_nb_ui
node_nb_ui -->|"renders cells"| node_render
node_render -->|"renders markdown"| node_markdown
node_render -->|"renders outputs"| node_images
node_images -->|"encodes graphics"| node_kitty
node_kitty -->|"writes graphics"| node_terminal
node_nb_ui -->|"attaches LSP"| node_lua_lsp
node_lua_lsp -->|"sends document sync"| node_lsp_server
node_nb_ui -->|"requests completion"| node_kernel_lsp
node_kernel_lsp -->|"proxies requests"| node_kernel_rpc
node_user -->|"opens remote tools"| node_remote_ui
node_remote_ui -->|"uses RPC"| node_rpc_lua
node_backend_connect -.->|"connects remotely"| node_ssh_host
node_core -->|"dispatches filesystem RPC"| node_remote_files
node_core -->|"dispatches process RPC"| node_remote_proc
node_core -->|"dispatches search RPC"| node_remote_search
node_remote_files -.->|"reads and writes"| node_ssh_host
node_remote_proc -.->|"spawns processes"| node_ssh_host
node_remote_search -.->|"searches files"| node_ssh_host

click node_lua_init "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/init.lua"
click node_nb_ui "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/init.lua"
click node_render "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/render.lua"
click node_markdown "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/markdown.lua"
click node_images "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/image.lua"
click node_lua_lsp "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/lsp/init.lua"
click node_kernel_lsp "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/lsp/kernel.lua"
click node_backend_connect "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/backend/connect.lua"
click node_rpc_lua "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/rpc.lua"
click node_core "https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/mod.rs"
click node_notebook_io "https://github.com/sheng-tse/jupynvim/blob/main/core/src/notebook.rs"
click node_session "https://github.com/sheng-tse/jupynvim/blob/main/core/src/session.rs"
click node_kernel_rpc "https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/exec.rs"
click node_kernelspec "https://github.com/sheng-tse/jupynvim/blob/main/core/src/kernelspec.rs"
click node_kernel_wire "https://github.com/sheng-tse/jupynvim/blob/main/core/src/kernel.rs"
click node_kitty "https://github.com/sheng-tse/jupynvim/blob/main/core/src/kitty.rs"
click node_remote_ui "https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/remote/dashboard.lua"
click node_remote_files "https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/fs.rs"
click node_remote_proc "https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/proc.rs"
click node_remote_search "https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/search.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_lua_init,node_nb_ui,node_render,node_markdown,node_images,node_lua_lsp,node_kernel_lsp,node_kitty,node_user toneBlue
class node_backend_connect,node_rpc_lua,node_core,node_notebook_io,node_session toneAmber
class node_kernel_rpc,node_kernelspec,node_kernel_wire,node_lsp_server toneMint
class node_remote_ui,node_remote_files,node_remote_proc,node_remote_search toneRose
class node_jupyter_kernel,node_ssh_host,node_terminal toneIndigo
```

## Components

### Neovim editor

- [Plugin setup](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/init.lua): `lua/jupynvim/init.lua`
- [Notebook editing](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/init.lua): `lua/jupynvim/notebook/init.lua`
- [Cell rendering](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/render.lua): `lua/jupynvim/notebook/render.lua`
- [Markdown cells](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/markdown.lua): `lua/jupynvim/notebook/markdown.lua`
- [Image display](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/notebook/image.lua): `lua/jupynvim/notebook/image.lua`
- [Notebook LSP](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/lsp/init.lua): `lua/jupynvim/lsp/init.lua`
- [Kernel LSP proxy](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/lsp/kernel.lua): `lua/jupynvim/lsp/kernel.lua`
- [Kitty graphics](https://github.com/sheng-tse/jupynvim/blob/main/core/src/kitty.rs): `core/src/kitty.rs`

### Notebook runtime

- [Backend connection](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/backend/connect.lua): `lua/jupynvim/backend/connect.lua`
- [Lua RPC client](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/rpc.lua): `lua/jupynvim/rpc.lua`
- [RPC server](https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/mod.rs): `core/src/rpc/mod.rs`
- [Notebook format](https://github.com/sheng-tse/jupynvim/blob/main/core/src/notebook.rs): `core/src/notebook.rs`
- [Notebook session](https://github.com/sheng-tse/jupynvim/blob/main/core/src/session.rs): `core/src/session.rs`

### Kernel services

- [Execution RPCs](https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/exec.rs): `core/src/rpc/exec.rs`
- [Kernel discovery](https://github.com/sheng-tse/jupynvim/blob/main/core/src/kernelspec.rs): `core/src/kernelspec.rs`
- [Jupyter protocol](https://github.com/sheng-tse/jupynvim/blob/main/core/src/kernel.rs): `core/src/kernel.rs`

### Remote workspace

- [Remote workspace UI](https://github.com/sheng-tse/jupynvim/blob/main/lua/jupynvim/remote/dashboard.lua): `lua/jupynvim/remote/dashboard.lua`
- [Remote files](https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/fs.rs): `core/src/rpc/fs.rs`
- [Remote terminals](https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/proc.rs): `core/src/rpc/proc.rs`
- [Remote search](https://github.com/sheng-tse/jupynvim/blob/main/core/src/rpc/search.rs): `core/src/rpc/search.rs`

### Other components

- **Notebook user**
- **Jupyter kernel**
- **SSH host**
- **Language server**
- **Graphics terminal**

## Connections

- Notebook user → Plugin setup: opens notebook
- Plugin setup → Notebook editing: sets up
- Notebook editing → Backend connection: connects backend
- Backend connection → Lua RPC client: uses RPC
- Lua RPC client → RPC server: sends messages
- RPC server → Notebook format: reads and writes
- RPC server → Execution RPCs: dispatches
- Execution RPCs → Kernel discovery: selects kernel
- Execution RPCs → Notebook session: manages session
- Execution RPCs → Jupyter protocol: executes code
- Jupyter protocol → Jupyter kernel: Jupyter messages
- Jupyter protocol → Notebook session: streams events
- Notebook session → Notebook editing: returns notebook state
- Notebook editing → Cell rendering: renders cells
- Cell rendering → Markdown cells: renders markdown
- Cell rendering → Image display: renders outputs
- Image display → Kitty graphics: encodes graphics
- Kitty graphics → Graphics terminal: writes graphics
- Notebook editing → Notebook LSP: attaches LSP
- Notebook LSP → Language server: sends document sync
- Notebook editing → Kernel LSP proxy: requests completion
- Kernel LSP proxy → Execution RPCs: proxies requests
- Notebook user → Remote workspace UI: opens remote tools
- Remote workspace UI → Lua RPC client: uses RPC
- Backend connection → SSH host: connects remotely
- RPC server → Remote files: dispatches filesystem RPC
- RPC server → Remote terminals: dispatches process RPC
- RPC server → Remote search: dispatches search RPC
- Remote files → SSH host: reads and writes
- Remote terminals → SSH host: spawns processes
- Remote search → SSH host: searches files