# neovim/go-client architecture

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

- Interactive diagram: https://gitdiagram.com/neovim/go-client
- Repository: https://github.com/neovim/go-client

## Overview

##### Project type and purpose
- This is an open-source Go library (“go-client”) implementing a Neovim client.
- It provides:
- A MessagePack codec (msgpack package)
- An RPC layer over MessagePack (msgpack/rpc)
- A high-level Neovim API client (nvim package)
- Helpers for writing Go-side Neovim plugins (nvim/plugin)
- A testing harness (nvim/nvimtest)
- Example apps showing remote and plugin usage

##### File structure
- Top-level: CI config, module files, LICENSE, README.
- “msgpack/”: pure serialization + pack/unpack + field metadata + tests.
- “msgpack/rpc/”: wiring of RPC calls over streams.
- “nvim/”: core client code (API definitions, helpers, UNIX/Windows transports, types, example tests).
- “nvim/plugin/”: code and tests for embedding Go in Neovim as a plugin.
- “nvim/nvimtest/”: in-process Neovim test harness.
- “examples/”: two standalone apps:
- remote client demo (Go main.go)
- plugin demo (Lua script)

##### README for additional insights
- Confirms its purpose: a Go Neovim client.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Examples
    subgraph "Examples" 
        direction TB
        RemoteClient["Standalone Remote Client"]:::example
        LuaPluginDemo["Lua Plugin Demo"]:::example
    end

    %% Core Layers
    GoApp["Go App/Plugin Entry Point"]:::external

    subgraph "High-Level API Client"
        direction TB
        APIClient["nvim package (API Client)"]:::api
    end

    subgraph "RPC Layer"
        direction TB
        RPCLayer["msgpack/rpc package"]:::rpc
    end

    subgraph "Serialization Codec"
        direction TB
        Codec["msgpack package"]:::serialization
    end

    subgraph "Transport Layer"
        direction TB
        Transport["Unix & Windows Transports"]:::transport
    end

    Neovim["Neovim Process"]:::external

    %% Plugin Helpers
    subgraph "Plugin Support (nvim/plugin)"
        direction TB
        PluginGo["plugin.go"]:::plugin
        PluginMain["main.go"]:::plugin
    end

    %% Test Harness
    nvimTest["nvimtest Test Harness"]:::test

    %% Connections for standalone client
    RemoteClient -->|"uses"| APIClient
    APIClient -->|"calls RPC"| RPCLayer
    RPCLayer -->|"encodes/decodes"| Codec
    Codec -->|"reads/writes []byte"| Transport
    Transport -->|"stdin/stdout or socket"| Neovim
    Neovim -->|"responses"| Transport
    Transport -->|"[]byte"| Codec
    Codec -->|"unpacked values"| RPCLayer
    RPCLayer -->|"RPC responses"| APIClient
    APIClient -->|"returns results"| RemoteClient

    %% Connections for plugin
    Neovim -->|"Msgpack-RPC calls"| RPCLayer
    RPCLayer -->|"dispatch to plugin"| PluginGo
    PluginGo -->|"invokes helper"| PluginMain
    PluginMain -->|"uses RPC server"| RPCLayer
    RPCLayer -->|"Msgpack-RPC"| Neovim

    %% Test harness connection
    nvimTest -->|"mocks Neovim on"| Transport

    %% Click events
    click RemoteClient "https://github.com/neovim/go-client/blob/main/examples/remote/helloremote/main.go"
    click LuaPluginDemo "https://github.com/neovim/go-client/blob/main/examples/remote/plugin/hello.lua"
    click APIClient "https://github.com/neovim/go-client/tree/main/nvim/"
    click RPCLayer "https://github.com/neovim/go-client/tree/main/msgpack/rpc/"
    click Codec "https://github.com/neovim/go-client/tree/main/msgpack/"
    click Transport "https://github.com/neovim/go-client/blob/main/nvim/nvim_unix.go"
    click PluginGo "https://github.com/neovim/go-client/blob/main/nvim/plugin/plugin.go"
    click PluginMain "https://github.com/neovim/go-client/blob/main/nvim/plugin/main.go"
    click nvimTest "https://github.com/neovim/go-client/blob/main/nvim/nvimtest/nvimtest.go"

    %% Styles
    classDef serialization fill:#e0f7fa,stroke:#00796b
    classDef rpc fill:#e0f2f1,stroke:#004d40
    classDef api fill:#e8f5e9,stroke:#1b5e20
    classDef transport fill:#fff3e0,stroke:#e65100
    classDef external fill:#eceff1,stroke:#607d8b
    classDef example fill:#fce4ec,stroke:#880e4f,stroke-dasharray: 5 5
    classDef plugin fill:#e1f5fe,stroke:#01579b
    classDef test fill:#f3e5f5,stroke:#6a1b9a
```
