# neovateai/neovate-code architecture

> Architecture diagram of the GitHub repository neovateai/neovate-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neovateai/neovate-code
- Repository: https://github.com/neovateai/neovate-code

## Overview

##### Project type and purpose
- Neovate Code is an open-source, multi-platform coding agent.
- It provides a CLI (“neovate” / “neo”) that developers run in the terminal.
- It also includes an optional browser-based UI and a VSCode extension.
- Under the hood it spins up a local server process to orchestrate LLM calls, file I/O, and tool executions.

##### File structure
- Top-level “src”—implements the core CLI application, server, commands, message bus, providers (LLMs), tools, plugins, slash-commands, session management, and utilities.
- “browser” folder—a standalone React/Vite web client that calls the server’s REST/WebSocket routes.
- “vscode-extension”—a VSCode extension that embeds an “mcp-server” (multi-channel protocol) to speak with the core.
- “e2e”, “examples”, “scripts” and tests—end-to-end fixtures and helper scripts for CI and examples.
- Configuration files: pnpm-workspace.yaml (monorepo), tsconfigs, GitHub Actions workflow.

##### README for additional insights
- Describes end-user flows: install CLI, run `/login`, `/model`, then free-form prompts.
- Mentions API key management, provider selection, tool invocation, code review, fix, generation.

1. CLI Client (neovate CLI binary)
2. Local Server Process
- HTTP / WebSocket API Layer (routes: app-data, files, completions, mcp, settings, tool-approval)
- Core Engine (messageBus, session, command parser, slash-commands)
- LLM Providers (GitHub Copilot, OpenAI, etc.)
- Tool Executor (shell commands, file read/write, git, external editor)
- Plugins & Output Style modules
3. Browser UI (React / Vite App)
4. VSCode Extension (mcp-server shim, extension.ts)
5. External Services
- LLM APIs
- GitHub (for git operations)
6. File System & Developer Project (workspace files)

- CLI Client → Local Server (IPC/child process stdio or HTTP)
- Browser UI → Local Server (HTTP / WebSocket)
- VSCode Extension → Local Server (mcp protocol over stdio or websocketTransport)
- Local Server → LLM Providers (HTTPS)
- Local Server → File System & git (tools via plugin/tool-executor)
- Core Engine ↔ Message Bus (internal event propagation)

c. Architectural patterns and design principles:
- Modular monorepo with clear separation between UI, server, and core logic.
- Plugin pattern for tools and output-styles (src/plugins & src/output-style).
- Slash-commands engine for extendable CLI commands (src/slash-commands).
- Event-driven message bus for decoupling CLI inputs, server operations, and tool calls.
- REST/WebSocket hybrid for browser UI performance and real-time updates.

d. Key technologies/frameworks:
- Node.js + TypeScript
- pnpm monorepo
- React + Vite + Tailwind (browser client)
- VSCode Extension API + esbuild
- Express-style server (custom)
- Lexical for chat input editing
- Vitest for unit tests / e2e fixtures

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-ends
    subgraph "Front-ends"
        CLI["CLI Client"]:::frontend
        Browser["Browser UI"]:::frontend
        VSCode["VSCode Extension"]:::frontend
    end

    %% Local Server Process
    subgraph "Local Server Process"
        subgraph "API Layer"
            AppData["app-data routes"]:::server
            Files["files routes"]:::server
            Completions["completions routes"]:::server
            MCP["mcp routes"]:::server
            Settings["settings routes"]:::server
            ToolApproval["tool-approval routes"]:::server
            WebServer["web-server"]:::server
        end

        subgraph "Core Engine"
            MessageBus["Message Bus"]:::server
            Session["Session"]:::server
            Loop["Loop"]:::server
            Context["Context"]:::server
            SlashCmd["Slash-Commands Engine"]:::server
            ServerCommands["Server Commands"]:::server
        end

        subgraph "LLM Providers"
            GitHubCopilot["GitHub Copilot Provider"]:::server
            AllProviders["Other Providers"]:::server
        end

        subgraph "Tool Executor"
            Tools["Tool Executor"]:::server
        end

        subgraph "Plugins & Output Style"
            Plugins["Plugins"]:::server
            OutputStyle["Output Style Modules"]:::server
        end
    end

    %% External
    ExternalLLM["LLM APIs"]:::external
    FileSystem["File System"]:::external
    GitHub["GitHub"]:::external

    %% Relationships
    CLI -->|"stdio (IPC)"| AppData
    Browser -->|"HTTP/WebSocket"| AppData
    VSCode -->|"mcp protocol"| AppData

    AppData -->|"request"| MessageBus
    Files -->|"request"| MessageBus
    Completions -->|"request"| MessageBus
    MCP -->|"request"| MessageBus
    Settings -->|"request"| MessageBus
    ToolApproval -->|"request"| MessageBus
    WebServer -->|"serves UI"| Browser

    MessageBus <--> Loop
    MessageBus <--> SlashCmd
    Loop --> Context
    SlashCmd --> Session

    MessageBus -->|"calls"| GitHubCopilot
    MessageBus -->|"calls"| AllProviders
    MessageBus -->|"executes"| Tools
    MessageBus -->|"loads"| Plugins
    MessageBus -->|"loads"| OutputStyle

    Tools -->|"FS ops"| FileSystem
    Tools -->|"git ops"| GitHub

    GitHubCopilot -->|"HTTPS"| ExternalLLM
    AllProviders -->|"HTTPS"| ExternalLLM

    %% Click Events
    click CLI "https://github.com/neovateai/neovate-code/blob/master/src/cli.ts"
    click Browser "https://github.com/neovateai/neovate-code/tree/master/browser/"
    click VSCode "https://github.com/neovateai/neovate-code/blob/master/vscode-extension/src/extension.ts"

    click AppData "https://github.com/neovateai/neovate-code/blob/master/src/server/routes/app-data.ts"
    click Files "https://github.com/neovateai/neovate-code/blob/master/src/server/routes/files.ts"
    click Completions "https://github.com/neovateai/neovate-code/blob/master/src/server/routes/completions.ts"
    click MCP "https://github.com/neovateai/neovate-code/blob/master/src/server/routes/mcp.ts"
    click Settings "https://github.com/neovateai/neovate-code/blob/master/src/server/routes/settings.ts"
    click ToolApproval "https://github.com/neovateai/neovate-code/blob/master/src/server/routes/tool-approval.ts"
    click WebServer "https://github.com/neovateai/neovate-code/blob/master/src/server/routes/web-server.ts"

    click MessageBus "https://github.com/neovateai/neovate-code/blob/master/src/messageBus.ts"
    click Session "https://github.com/neovateai/neovate-code/blob/master/src/session.ts"
    click Loop "https://github.com/neovateai/neovate-code/blob/master/src/loop.ts"
    click Context "https://github.com/neovateai/neovate-code/blob/master/src/context.ts"
    click SlashCmd "https://github.com/neovateai/neovate-code/blob/master/src/slashCommand.ts"
    click ServerCommands "https://github.com/neovateai/neovate-code/blob/master/src/commands/server.ts"

    click GitHubCopilot "https://github.com/neovateai/neovate-code/blob/master/src/providers/githubCopilot.ts"
    click AllProviders "https://github.com/neovateai/neovate-code/tree/master/src/providers/"

    click Tools "https://github.com/neovateai/neovate-code/blob/master/src/tool.ts"

    click Plugins "https://github.com/neovateai/neovate-code/tree/master/src/plugins/"
    click OutputStyle "https://github.com/neovateai/neovate-code/tree/master/src/output-style/"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px
    classDef server fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#bfb,stroke:#333,stroke-width:1px
```
