# ysunyang979-sys/nexus-web-chatgpt architecture

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

- Interactive diagram: https://gitdiagram.com/ysunyang979-sys/nexus-web-chatgpt
- Repository: https://github.com/ysunyang979-sys/nexus-web-chatgpt

## Overview

Nexus is a local AI control plane: an AI client sends MCP requests through the server, which brokers work to an outbound-connected local Runner; the Runner applies project boundaries and performs development operations. The desktop control center lets the local user configure projects, tokens, approvals, and integrations. The graph includes the README’s major capabilities and a few documented internal layers; sampled excerpts are partial, so uncertain module-to-module calls are omitted.

Main entry points: [`apps/runner/src/rpc/router.ts`](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/rpc/router.ts) (RPC handlers), [`apps/server/src/mcp/tools`](https://github.com/ysunyang979-sys/nexus-web-chatgpt/tree/main/apps/server/src/mcp/tools) (MCP tools), [`apps/server/src/runner/rpc-service.ts`](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/runner/rpc-service.ts) (Runner RPC service), [`packages/security/src/policy/evaluator.ts`](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/packages/security/src/policy/evaluator.ts) (Policy and sandbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client Access"]
  node_desktop["Desktop control center<br/>[App.tsx]"]
  node_bridge["Local bridge<br/>[server.ts]"]
end

subgraph group_control["Control Plane"]
  node_mcp["MCP interface<br/>[server.ts]"]
  node_mcp_tools["MCP tools"]
  node_rpc_service["Runner RPC service<br/>[rpc-service.ts]"]
  node_runner_ws["Runner connection<br/>[runner-ws.ts]"]
end

subgraph group_execution["Local Execution"]
  node_runner["Runner daemon<br/>[runner.ts]"]
  node_rpc_router["RPC handlers<br/>[router.ts]"]
  node_projects["Project registry<br/>[registry.ts]"]
  node_filesystem["Filesystem tools<br/>[service.ts]"]
  node_git_worktree["Git and worktrees<br/>[service.ts]"]
  node_process["Processes and terminals<br/>[service.ts]"]
  node_jobs_runtime["Jobs and runtimes<br/>[manager.ts]"]
  node_lsp["Code intelligence<br/>[manager.ts]"]
end

subgraph group_workflow["Workflow Services"]
  node_approvals["Approval gates<br/>[manager.ts]"]
  node_sessions["Workflow sessions<br/>[manager.ts]"]
  node_skills["Skills<br/>[skill-registry.ts]"]
end

subgraph group_foundation["Security and State"]
  node_security["Policy and sandbox<br/>[evaluator.ts]"]
  node_database[("Server persistence<br/>[schema.ts]")]
  node_protocol["Shared RPC protocol<br/>[rpc.ts]"]
end

node_ai(("AI client"))
node_user(("Local user"))

node_ai -->|"sends MCP requests"| node_mcp
node_desktop -->|"presents controls"| node_user
node_user -->|"configures system"| node_desktop
node_user -->|"authorizes locally"| node_projects
node_mcp -->|"dispatches tools"| node_mcp_tools
node_mcp_tools -->|"requests runner work"| node_rpc_service
node_rpc_service -->|"sends RPC"| node_runner_ws
node_runner_ws -->|"carries messages"| node_runner
node_runner -->|"dispatches requests"| node_rpc_router
node_rpc_router -->|"queries projects"| node_projects
node_rpc_router -->|"invokes file operations"| node_filesystem
node_rpc_router -->|"invokes repository operations"| node_git_worktree
node_rpc_router -->|"invokes process tools"| node_process
node_rpc_router -->|"invokes execution tools"| node_jobs_runtime
node_rpc_router -->|"requests code intelligence"| node_lsp
node_rpc_router -->|"manages approvals"| node_approvals
node_mcp_tools -->|"serves session tools"| node_sessions
node_mcp_tools -->|"serves skill tools"| node_skills
node_sessions -->|"stores checkpoints"| node_database
node_security -->|"constrains paths"| node_filesystem
node_security -->|"evaluates commands"| node_process
node_protocol -.->|"defines RPC types"| node_rpc_service
node_protocol -.->|"defines RPC types"| node_rpc_router

click node_desktop "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/desktop/src/App.tsx"
click node_bridge "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/bridge/src/server.ts"
click node_mcp "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/mcp/server.ts"
click node_mcp_tools "https://github.com/ysunyang979-sys/nexus-web-chatgpt/tree/main/apps/server/src/mcp/tools"
click node_rpc_service "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/runner/rpc-service.ts"
click node_runner_ws "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/routes/runner-ws.ts"
click node_runner "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/runner.ts"
click node_rpc_router "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/rpc/router.ts"
click node_projects "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/projects/registry.ts"
click node_filesystem "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/filesystem/service.ts"
click node_git_worktree "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/git/service.ts"
click node_process "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/process/service.ts"
click node_jobs_runtime "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/jobs/manager.ts"
click node_lsp "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/lsp/manager.ts"
click node_approvals "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/approvals/manager.ts"
click node_sessions "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/session/manager.ts"
click node_skills "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/skills/skill-registry.ts"
click node_security "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/packages/security/src/policy/evaluator.ts"
click node_database "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/db/schema.ts"
click node_protocol "https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/packages/protocol/src/runner/rpc.ts"

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_desktop,node_bridge,node_ai,node_user toneBlue
class node_mcp,node_mcp_tools,node_rpc_service,node_runner_ws toneAmber
class node_runner,node_rpc_router,node_projects,node_filesystem,node_git_worktree,node_process,node_jobs_runtime,node_lsp toneMint
class node_approvals,node_sessions,node_skills toneRose
class node_security,node_database,node_protocol toneIndigo
```

## Components

### Client Access

- [Desktop control center](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/desktop/src/App.tsx): `apps/desktop/src/App.tsx`
- [Local bridge](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/bridge/src/server.ts): `apps/bridge/src/server.ts`

### Control Plane

- [MCP interface](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/mcp/server.ts): `apps/server/src/mcp/server.ts`
- [MCP tools](https://github.com/ysunyang979-sys/nexus-web-chatgpt/tree/main/apps/server/src/mcp/tools): `apps/server/src/mcp/tools`
- [Runner RPC service](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/runner/rpc-service.ts): `apps/server/src/runner/rpc-service.ts`
- [Runner connection](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/routes/runner-ws.ts): `apps/server/src/routes/runner-ws.ts`

### Local Execution

- [Runner daemon](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/runner.ts): `apps/runner/src/runner.ts`
- [RPC handlers](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/rpc/router.ts): `apps/runner/src/rpc/router.ts`
- [Project registry](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/projects/registry.ts): `apps/runner/src/projects/registry.ts`
- [Filesystem tools](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/filesystem/service.ts): `apps/runner/src/filesystem/service.ts`
- [Git and worktrees](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/git/service.ts): `apps/runner/src/git/service.ts`
- [Processes and terminals](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/process/service.ts): `apps/runner/src/process/service.ts`
- [Jobs and runtimes](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/jobs/manager.ts): `apps/runner/src/jobs/manager.ts`
- [Code intelligence](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/lsp/manager.ts): `apps/runner/src/lsp/manager.ts`

### Workflow Services

- [Approval gates](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/runner/src/approvals/manager.ts): `apps/runner/src/approvals/manager.ts`
- [Workflow sessions](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/session/manager.ts): `apps/server/src/session/manager.ts`
- [Skills](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/skills/skill-registry.ts): `apps/server/src/skills/skill-registry.ts`

### Security and State

- [Policy and sandbox](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/packages/security/src/policy/evaluator.ts): `packages/security/src/policy/evaluator.ts`
- [Server persistence](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/apps/server/src/db/schema.ts): `apps/server/src/db/schema.ts`
- [Shared RPC protocol](https://github.com/ysunyang979-sys/nexus-web-chatgpt/blob/main/packages/protocol/src/runner/rpc.ts): `packages/protocol/src/runner/rpc.ts`

### Other components

- **AI client**
- **Local user**

## Connections

- AI client → MCP interface: sends MCP requests
- Desktop control center → Local user: presents controls
- Local user → Desktop control center: configures system
- Local user → Project registry: authorizes locally
- MCP interface → MCP tools: dispatches tools
- MCP tools → Runner RPC service: requests runner work
- Runner RPC service → Runner connection: sends RPC
- Runner connection → Runner daemon: carries messages
- Runner daemon → RPC handlers: dispatches requests
- RPC handlers → Project registry: queries projects
- RPC handlers → Filesystem tools: invokes file operations
- RPC handlers → Git and worktrees: invokes repository operations
- RPC handlers → Processes and terminals: invokes process tools
- RPC handlers → Jobs and runtimes: invokes execution tools
- RPC handlers → Code intelligence: requests code intelligence
- RPC handlers → Approval gates: manages approvals
- MCP tools → Workflow sessions: serves session tools
- MCP tools → Skills: serves skill tools
- Workflow sessions → Server persistence: stores checkpoints
- Policy and sandbox → Filesystem tools: constrains paths
- Policy and sandbox → Processes and terminals: evaluates commands
- Shared RPC protocol → Runner RPC service: defines RPC types
- Shared RPC protocol → RPC handlers: defines RPC types