# monkoose/neocodeium architecture

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

- Interactive diagram: https://gitdiagram.com/monkoose/neocodeium
- Repository: https://github.com/monkoose/neocodeium

## Overview

NeoCodeium is a Neovim plugin for Windsurf AI completions. The user configures the plugin, requests or receives suggestions, and accepts, edits, cycles, or clears them through its API. The README also documents authentication, enterprise server settings, and Windsurf Chat workspace-root configuration. It explicitly describes code being sent to Windsurf’s server for completion; source excerpts were not provided, so internal call relationships are not asserted.

Main entry points: [`lua/neocodeium/server.lua`](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/server.lua) (Language server), [`lua/neocodeium/binary.lua`](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/binary.lua) (Server binary), [`lua/neocodeium/init.lua`](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/init.lua) (Plugin API), [`lua/neocodeium/commands.lua`](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/commands.lua) (Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Plugin interface"]
  node_api["Plugin API<br/>[init.lua]"]
  node_commands["Commands<br/>[commands.lua]"]
  node_options["Configuration<br/>[options.lua]"]
end

subgraph group_completion["Completion experience"]
  node_completer["Completion engine<br/>[completer.lua]"]
  node_renderer["Suggestion renderer<br/>[renderer.lua]"]
  node_state["Plugin state<br/>[state.lua]"]
  node_events["User events<br/>[events.lua]"]
  node_filetype["Filetype handling<br/>[filetype.lua]"]
end

subgraph group_windsurf["Windsurf services"]
  node_chat["Windsurf Chat<br/>[chat.lua]"]
  node_auth["API authentication<br/>[api_key.lua]"]
  node_server["Language server<br/>[server.lua]"]
  node_windsurf(("Windsurf service"))
  node_binary["Server binary<br/>[binary.lua]"]
end

subgraph group_support["Runtime support"]
  node_health["Health checks<br/>[health.lua]"]
  node_log["Logging<br/>[log.lua]"]
  node_doc["Help documentation<br/>[doc.lua]"]
  node_utils["Utilities<br/>[init.lua]"]
  node_stdio["Process I/O<br/>[stdio.lua]"]
  node_conf["Config utilities<br/>[conf.lua]"]
end

node_user(("Neovim user"))

node_user -->|"configures and invokes"| node_api
node_user -->|"runs auth command"| node_commands
node_server -->|"sends code; receives completions"| node_windsurf
node_user -->|"configures workspace roots"| node_chat
node_binary -->|"downloads from portal"| node_windsurf

click node_api "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/init.lua"
click node_commands "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/commands.lua"
click node_options "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/options.lua"
click node_completer "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/completer.lua"
click node_renderer "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/renderer.lua"
click node_state "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/state.lua"
click node_events "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/events.lua"
click node_filetype "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/filetype.lua"
click node_chat "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/chat.lua"
click node_auth "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/api_key.lua"
click node_server "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/server.lua"
click node_binary "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/binary.lua"
click node_health "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/health.lua"
click node_log "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/log.lua"
click node_doc "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/doc.lua"
click node_utils "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/utils/init.lua"
click node_stdio "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/utils/stdio.lua"
click node_conf "https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/utils/conf.lua"

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_api,node_commands,node_options,node_user toneBlue
class node_completer,node_renderer,node_state,node_events,node_filetype toneAmber
class node_chat,node_auth,node_server,node_windsurf,node_binary toneMint
class node_health,node_log,node_doc,node_utils,node_stdio,node_conf toneRose
```

## Components

### Plugin interface

- [Plugin API](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/init.lua): `lua/neocodeium/init.lua`
- [Commands](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/commands.lua): `lua/neocodeium/commands.lua`
- [Configuration](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/options.lua): `lua/neocodeium/options.lua`

### Completion experience

- [Completion engine](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/completer.lua): `lua/neocodeium/completer.lua`
- [Suggestion renderer](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/renderer.lua): `lua/neocodeium/renderer.lua`
- [Plugin state](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/state.lua): `lua/neocodeium/state.lua`
- [User events](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/events.lua): `lua/neocodeium/events.lua`
- [Filetype handling](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/filetype.lua): `lua/neocodeium/filetype.lua`

### Windsurf services

- [Windsurf Chat](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/chat.lua): `lua/neocodeium/chat.lua`
- [API authentication](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/api_key.lua): `lua/neocodeium/api_key.lua`
- [Language server](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/server.lua): `lua/neocodeium/server.lua`
- **Windsurf service**
- [Server binary](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/binary.lua): `lua/neocodeium/binary.lua`

### Runtime support

- [Health checks](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/health.lua): `lua/neocodeium/health.lua`
- [Logging](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/log.lua): `lua/neocodeium/log.lua`
- [Help documentation](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/doc.lua): `lua/neocodeium/doc.lua`
- [Utilities](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/utils/init.lua): `lua/neocodeium/utils/init.lua`
- [Process I/O](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/utils/stdio.lua): `lua/neocodeium/utils/stdio.lua`
- [Config utilities](https://github.com/monkoose/neocodeium/blob/main/lua/neocodeium/utils/conf.lua): `lua/neocodeium/utils/conf.lua`

### Other components

- **Neovim user**

## Connections

- Neovim user → Plugin API: configures and invokes (evidence: `README.md`)
- Neovim user → Commands: runs auth command (evidence: `README.md`)
- Language server → Windsurf service: sends code; receives completions (evidence: `README.md`)
- Neovim user → Windsurf Chat: configures workspace roots (evidence: `README.md`)
- Server binary → Windsurf service: downloads from portal (evidence: `README.md`)