# vsndrg/nvim architecture

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

- Interactive diagram: https://gitdiagram.com/vsndrg/nvim
- Repository: https://github.com/vsndrg/nvim

## Overview

This repository is primarily a Neovim configuration, with a substantial embedded Markdown preview and a separate preview-agent automation tool. The main user workflow is editing in Neovim with configured language and editor features; the preview subsystem turns Markdown into an interactive rendered page, while the agent subsystem orchestrates implementation steps with policy hooks. The graph preserves the documented-by-code preview and agent components, but the empty README and unsampled Neovim/plugin sources limit evidence for their wiring and capabilities.

Main entry points: [`mdpreview/web/src/main.js`](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/main.js) (Preview Interface), [`preview/agent/hooks/policy.py`](https://github.com/vsndrg/nvim/blob/main/preview/agent/hooks/policy.py) (Shared Policy), [`mdpreview/web/src/find.js`](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/find.js) (In-Page Search), [`mdpreview/web/src/viewport.js`](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/viewport.js) (Viewport Control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Neovim Configuration"]
  node_nvim["Neovim Setup<br/>[init.lua]"]
  node_editor_options["Editor Options<br/>[options.lua]"]
  node_keymaps["Keybindings<br/>[keymaps.lua]"]
  node_language_support["Language Support"]
  node_plugin_configs["Plugin Features"]
  node_md_entry["Preview Plugin<br/>[mdpreview.lua]"]
end

subgraph group_markdown["Markdown Preview"]
  node_web_main["Preview Interface<br/>[main.js]"]
  node_markdown_render["Markdown Renderer<br/>[render.js]"]
  node_mermaid["Diagram Rendering<br/>[mermaid.js]"]
  node_scroll_sync["Line Sync<br/>[scroll-sync.js]"]
  node_search["In-Page Search<br/>[find.js]"]
  node_motion["Scroll Motion<br/>[scroller.js]"]
  node_viewport["Viewport Control<br/>[viewport.js]"]
end

subgraph group_agent["Preview Agent"]
  node_agent_runner["Step Orchestrator<br/>[run.py]"]
  node_hook_guard["Action Guard<br/>[guard.py]"]
  node_hook_policy["Shared Policy<br/>[policy.py]"]
  node_hook_restore["Change Restore<br/>[restore.py]"]
end

node_user(("Editor User"))

node_user -->|"edits in"| node_nvim
node_web_main -->|"renders with"| node_markdown_render
node_web_main -->|"renders diagrams"| node_mermaid
node_web_main -->|"invalidates cache"| node_scroll_sync
node_web_main -->|"searches with"| node_search
node_search -->|"moves viewport"| node_viewport
node_motion -->|"plays motions"| node_viewport
node_hook_guard -->|"uses policy"| node_hook_policy
node_hook_restore -->|"uses policy"| node_hook_policy
node_agent_runner -->|"uses policy"| node_hook_policy

click node_nvim "https://github.com/vsndrg/nvim/blob/main/init.lua"
click node_editor_options "https://github.com/vsndrg/nvim/blob/main/lua/options.lua"
click node_keymaps "https://github.com/vsndrg/nvim/blob/main/lua/keymaps.lua"
click node_language_support "https://github.com/vsndrg/nvim/tree/main/lua/lang"
click node_plugin_configs "https://github.com/vsndrg/nvim/tree/main/lua/plugins"
click node_md_entry "https://github.com/vsndrg/nvim/blob/main/lua/plugins/mdpreview.lua"
click node_web_main "https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/main.js"
click node_markdown_render "https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/render.js"
click node_mermaid "https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/mermaid.js"
click node_scroll_sync "https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/scroll-sync.js"
click node_search "https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/find.js"
click node_motion "https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/scroller.js"
click node_viewport "https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/viewport.js"
click node_agent_runner "https://github.com/vsndrg/nvim/blob/main/preview/agent/run.py"
click node_hook_guard "https://github.com/vsndrg/nvim/blob/main/preview/agent/hooks/guard.py"
click node_hook_policy "https://github.com/vsndrg/nvim/blob/main/preview/agent/hooks/policy.py"
click node_hook_restore "https://github.com/vsndrg/nvim/blob/main/preview/agent/hooks/restore.py"

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_nvim,node_editor_options,node_keymaps,node_language_support,node_plugin_configs,node_md_entry,node_user toneBlue
class node_web_main,node_markdown_render,node_mermaid,node_scroll_sync,node_search,node_motion,node_viewport toneAmber
class node_agent_runner,node_hook_guard,node_hook_policy,node_hook_restore toneMint
```

## Components

### Neovim Configuration

- [Neovim Setup](https://github.com/vsndrg/nvim/blob/main/init.lua): `init.lua`
- [Editor Options](https://github.com/vsndrg/nvim/blob/main/lua/options.lua): `lua/options.lua`
- [Keybindings](https://github.com/vsndrg/nvim/blob/main/lua/keymaps.lua): `lua/keymaps.lua`
- [Language Support](https://github.com/vsndrg/nvim/tree/main/lua/lang): `lua/lang`
- [Plugin Features](https://github.com/vsndrg/nvim/tree/main/lua/plugins): `lua/plugins`
- [Preview Plugin](https://github.com/vsndrg/nvim/blob/main/lua/plugins/mdpreview.lua): `lua/plugins/mdpreview.lua`

### Markdown Preview

- [Preview Interface](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/main.js): `mdpreview/web/src/main.js`
- [Markdown Renderer](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/render.js): `mdpreview/web/src/render.js`
- [Diagram Rendering](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/mermaid.js): `mdpreview/web/src/mermaid.js`
- [Line Sync](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/scroll-sync.js): `mdpreview/web/src/scroll-sync.js`
- [In-Page Search](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/find.js): `mdpreview/web/src/find.js`
- [Scroll Motion](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/scroller.js): `mdpreview/web/src/scroller.js`
- [Viewport Control](https://github.com/vsndrg/nvim/blob/main/mdpreview/web/src/viewport.js): `mdpreview/web/src/viewport.js`

### Preview Agent

- [Step Orchestrator](https://github.com/vsndrg/nvim/blob/main/preview/agent/run.py): `preview/agent/run.py`
- [Action Guard](https://github.com/vsndrg/nvim/blob/main/preview/agent/hooks/guard.py): `preview/agent/hooks/guard.py`
- [Shared Policy](https://github.com/vsndrg/nvim/blob/main/preview/agent/hooks/policy.py): `preview/agent/hooks/policy.py`
- [Change Restore](https://github.com/vsndrg/nvim/blob/main/preview/agent/hooks/restore.py): `preview/agent/hooks/restore.py`

### Other components

- **Editor User**

## Connections

- Editor User → Neovim Setup: edits in
- Preview Interface → Markdown Renderer: renders with (evidence: `mdpreview/web/src/main.js`)
- Preview Interface → Diagram Rendering: renders diagrams (evidence: `mdpreview/web/src/main.js`)
- Preview Interface → Line Sync: invalidates cache (evidence: `mdpreview/web/src/main.js`)
- Preview Interface → In-Page Search: searches with (evidence: `mdpreview/web/src/main.js`)
- In-Page Search → Viewport Control: moves viewport (evidence: `mdpreview/web/src/find.js`)
- Scroll Motion → Viewport Control: plays motions (evidence: `mdpreview/web/src/scroller.js`)
- Action Guard → Shared Policy: uses policy (evidence: `preview/agent/hooks/guard.py`)
- Change Restore → Shared Policy: uses policy (evidence: `preview/agent/hooks/restore.py`)
- Step Orchestrator → Shared Policy: uses policy (evidence: `preview/agent/run.py`)
