# m1k1o/neko architecture

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

- Interactive diagram: https://gitdiagram.com/m1k1o/neko
- Repository: https://github.com/m1k1o/neko

## Overview

Neko is a self-hosted virtual desktop/browser that streams an isolated Linux desktop to one or more users over WebRTC. A user loads the Vue client, authenticates through the HTTP API, joins a session over WebSocket, and receives audio/video while control, clipboard, keyboard, chat, and file actions are dispatched back to the server. Session management coordinates membership and permissions; desktop and capture layers access X11 and GStreamer. The graph emphasizes sampled runtime wiring; some API handlers and plugin routes are represented at their enclosing paths.

Main entry points: [`server/internal/session/manager.go`](https://github.com/m1k1o/neko/blob/master/server/internal/session/manager.go) (Session Manager), [`client/src/app.vue`](https://github.com/m1k1o/neko/blob/master/client/src/app.vue) (Vue Client), [`server/internal/websocket/manager.go`](https://github.com/m1k1o/neko/blob/master/server/internal/websocket/manager.go) (WebSocket Gateway), [`server/internal/websocket/handler/handler.go`](https://github.com/m1k1o/neko/blob/master/server/internal/websocket/handler/handler.go) (Message Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_ui["Vue Client<br/>[app.vue]"]
  node_client_state["Client State<br/>[index.ts]"]
  node_client_protocol["Neko Protocol<br/>[index.ts]"]
  node_browser_storage[("Browser Storage<br/>[localstorage.ts]")]
end

subgraph group_gateway["Gateway And Sessions"]
  node_http["HTTP Server<br/>[manager.go]"]
  node_api["API Router<br/>[router.go]"]
  node_ws["WebSocket Gateway<br/>[manager.go]"]
  node_ws_handlers["Message Handlers<br/>[handler.go]"]
  node_members["Member Manager<br/>[manager.go]"]
  node_member_provider["Member Providers"]
  node_sessions["Session Manager<br/>[manager.go]"]
end

subgraph group_desktop["Desktop And Media"]
  node_desktop_mgr["Desktop Manager<br/>[manager.go]"]
  node_capture["Capture Manager<br/>[manager.go]"]
  node_pipelines["Media Pipelines"]
  node_webrtc["WebRTC Manager<br/>[manager.go]"]
end

subgraph group_extensions["Extensions"]
  node_plugins["Plugin Manager<br/>[manager.go]"]
  node_chat["Chat Plugin<br/>[manager.go]"]
  node_files["File Transfer<br/>[manager.go]"]
end

node_user(("Participant"))
node_x11["X11 Desktop"]
node_gstreamer["GStreamer"]
node_file_system[("Shared Files")]

node_user -->|"opens client"| node_ui
node_ui -->|"API requests"| node_http
node_ui -->|"opens socket"| node_ws
node_ui -->|"updates state"| node_client_state
node_client_state -->|"reads settings"| node_browser_storage
node_client_protocol -->|"sends messages"| node_ws
node_http -->|"routes API"| node_api
node_http -->|"upgrades socket"| node_ws
node_api -->|"authenticates members"| node_members
node_api -->|"manages sessions"| node_sessions
node_members -->|"authenticates against"| node_member_provider
node_members -->|"creates sessions"| node_sessions
node_ws -->|"dispatches messages"| node_ws_handlers
node_ws_handlers -->|"updates session"| node_sessions
node_ws_handlers -->|"controls desktop"| node_desktop_mgr
node_ws_handlers -->|"signals peers"| node_webrtc
node_sessions -->|"broadcasts events"| node_ws
node_desktop_mgr -->|"controls display"| node_x11
node_capture -->|"reads screen"| node_desktop_mgr
node_capture -->|"builds pipelines"| node_pipelines
node_pipelines -->|"checks codecs"| node_gstreamer
node_capture -->|"captures media"| node_gstreamer
node_webrtc -->|"reads cursor"| node_desktop_mgr
node_webrtc -->|"starts streams"| node_capture
node_webrtc -->|"streams media"| node_ui
node_plugins -.->|"starts plugin"| node_chat
node_plugins -.->|"starts plugin"| node_files
node_chat -->|"broadcasts chat"| node_sessions
node_files -->|"broadcasts files"| node_sessions
node_files -->|"reads and writes"| node_file_system

click node_ui "https://github.com/m1k1o/neko/blob/master/client/src/app.vue"
click node_client_state "https://github.com/m1k1o/neko/blob/master/client/src/store/index.ts"
click node_client_protocol "https://github.com/m1k1o/neko/blob/master/client/src/neko/index.ts"
click node_browser_storage "https://github.com/m1k1o/neko/blob/master/client/src/utils/localstorage.ts"
click node_http "https://github.com/m1k1o/neko/blob/master/server/internal/http/manager.go"
click node_api "https://github.com/m1k1o/neko/blob/master/server/internal/api/router.go"
click node_ws "https://github.com/m1k1o/neko/blob/master/server/internal/websocket/manager.go"
click node_ws_handlers "https://github.com/m1k1o/neko/blob/master/server/internal/websocket/handler/handler.go"
click node_members "https://github.com/m1k1o/neko/blob/master/server/internal/member/manager.go"
click node_member_provider "https://github.com/m1k1o/neko/tree/master/server/internal/member"
click node_sessions "https://github.com/m1k1o/neko/blob/master/server/internal/session/manager.go"
click node_desktop_mgr "https://github.com/m1k1o/neko/blob/master/server/internal/desktop/manager.go"
click node_capture "https://github.com/m1k1o/neko/blob/master/server/internal/capture/manager.go"
click node_pipelines "https://github.com/m1k1o/neko/blob/master/server/internal/config/capture_pipeline.go"
click node_webrtc "https://github.com/m1k1o/neko/blob/master/server/internal/webrtc/manager.go"
click node_plugins "https://github.com/m1k1o/neko/blob/master/server/internal/plugins/manager.go"
click node_chat "https://github.com/m1k1o/neko/blob/master/server/internal/plugins/chat/manager.go"
click node_files "https://github.com/m1k1o/neko/blob/master/server/internal/plugins/filetransfer/manager.go"

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_ui,node_client_state,node_client_protocol,node_browser_storage toneBlue
class node_http,node_api,node_ws,node_ws_handlers,node_members,node_member_provider,node_sessions,node_file_system toneAmber
class node_desktop_mgr,node_capture,node_pipelines,node_webrtc toneMint
class node_plugins,node_chat,node_files toneRose
class node_user,node_x11,node_gstreamer toneIndigo
```

## Components

### Client

- [Vue Client](https://github.com/m1k1o/neko/blob/master/client/src/app.vue): `client/src/app.vue`
- [Client State](https://github.com/m1k1o/neko/blob/master/client/src/store/index.ts): `client/src/store/index.ts`
- [Neko Protocol](https://github.com/m1k1o/neko/blob/master/client/src/neko/index.ts): `client/src/neko/index.ts`
- [Browser Storage](https://github.com/m1k1o/neko/blob/master/client/src/utils/localstorage.ts): `client/src/utils/localstorage.ts`

### Gateway And Sessions

- [HTTP Server](https://github.com/m1k1o/neko/blob/master/server/internal/http/manager.go): `server/internal/http/manager.go`
- [API Router](https://github.com/m1k1o/neko/blob/master/server/internal/api/router.go): `server/internal/api/router.go`
- [WebSocket Gateway](https://github.com/m1k1o/neko/blob/master/server/internal/websocket/manager.go): `server/internal/websocket/manager.go`
- [Message Handlers](https://github.com/m1k1o/neko/blob/master/server/internal/websocket/handler/handler.go): `server/internal/websocket/handler/handler.go`
- [Member Manager](https://github.com/m1k1o/neko/blob/master/server/internal/member/manager.go): `server/internal/member/manager.go`
- [Member Providers](https://github.com/m1k1o/neko/tree/master/server/internal/member): `server/internal/member`
- [Session Manager](https://github.com/m1k1o/neko/blob/master/server/internal/session/manager.go): `server/internal/session/manager.go`

### Desktop And Media

- [Desktop Manager](https://github.com/m1k1o/neko/blob/master/server/internal/desktop/manager.go): `server/internal/desktop/manager.go`
- [Capture Manager](https://github.com/m1k1o/neko/blob/master/server/internal/capture/manager.go): `server/internal/capture/manager.go`
- [Media Pipelines](https://github.com/m1k1o/neko/blob/master/server/internal/config/capture_pipeline.go): `server/internal/config/capture_pipeline.go`
- [WebRTC Manager](https://github.com/m1k1o/neko/blob/master/server/internal/webrtc/manager.go): `server/internal/webrtc/manager.go`

### Extensions

- [Plugin Manager](https://github.com/m1k1o/neko/blob/master/server/internal/plugins/manager.go): `server/internal/plugins/manager.go`
- [Chat Plugin](https://github.com/m1k1o/neko/blob/master/server/internal/plugins/chat/manager.go): `server/internal/plugins/chat/manager.go`
- [File Transfer](https://github.com/m1k1o/neko/blob/master/server/internal/plugins/filetransfer/manager.go): `server/internal/plugins/filetransfer/manager.go`

### Other components

- **Participant**
- **X11 Desktop**
- **GStreamer**
- **Shared Files**

## Connections

- Participant → Vue Client: opens client
- Vue Client → HTTP Server: API requests
- Vue Client → WebSocket Gateway: opens socket
- Vue Client → Client State: updates state
- Client State → Browser Storage: reads settings
- Neko Protocol → WebSocket Gateway: sends messages
- HTTP Server → API Router: routes API
- HTTP Server → WebSocket Gateway: upgrades socket
- API Router → Member Manager: authenticates members
- API Router → Session Manager: manages sessions
- Member Manager → Member Providers: authenticates against
- Member Manager → Session Manager: creates sessions
- WebSocket Gateway → Message Handlers: dispatches messages
- Message Handlers → Session Manager: updates session
- Message Handlers → Desktop Manager: controls desktop
- Message Handlers → WebRTC Manager: signals peers
- Session Manager → WebSocket Gateway: broadcasts events
- Desktop Manager → X11 Desktop: controls display
- Capture Manager → Desktop Manager: reads screen
- Capture Manager → Media Pipelines: builds pipelines
- Media Pipelines → GStreamer: checks codecs
- Capture Manager → GStreamer: captures media
- WebRTC Manager → Desktop Manager: reads cursor
- WebRTC Manager → Capture Manager: starts streams
- WebRTC Manager → Vue Client: streams media
- Plugin Manager → Chat Plugin: starts plugin
- Plugin Manager → File Transfer: starts plugin
- Chat Plugin → Session Manager: broadcasts chat
- File Transfer → Session Manager: broadcasts files
- File Transfer → Shared Files: reads and writes
