# kashif-coder404/nexus-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/kashif-coder404/nexus-v2
- Repository: https://github.com/kashif-coder404/nexus-v2

## Overview

Nexus is a desktop AI assistant: a user chats through the web dashboard, the backend processes the request with an AI model, and the paired Windows agent provides local desktop execution and live device status. The product also includes authentication, chat history and memory, device pairing, search, screenshots, and system information. The tree and excerpts establish the chat-controller flow and parts of agent pairing/telemetry; several other subsystems are represented by their exact tree paths, but their internal call wiring was not sampled.

Main entry points: [`Local-BE-v2/Program.cs`](https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/Program.cs) (Windows agent), [`backend/controllers/chat.controller.ts`](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/controllers/chat.controller.ts) (Chat controller), [`backend/routes/chat.routes.ts`](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/routes/chat.routes.ts) (Chat routes), [`backend/AI/askAI.ts`](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/AI/askAI.ts) (AI orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web clients"]
  node_dashboard["Web dashboard<br/>[page.tsx]"]
  node_chatui["Chat interface<br/>[ChatUI.tsx]"]
end

subgraph group_cloud["Cloud backend"]
  node_chatroute["Chat routes<br/>[chat.routes.ts]"]
  node_chatcontroller["Chat controller<br/>[chat.controller.ts]"]
  node_auth["Authentication"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_devices["Device API<br/>[device.routes.ts]"]
  node_wscloud["Device websocket"]
end

subgraph group_intelligence["AI and tools"]
  node_ai["AI orchestration<br/>[askAI.ts]"]
  node_modelrouter["Model providers<br/>[CallAI.ts]"]
  node_instructions["Assistant behavior"]
  node_search["Search service<br/>[search.service.ts]"]
  node_searchtool["Filesystem search<br/>[search.py]"]
  node_exec["Command execution<br/>[execute.service.ts]"]
end

subgraph group_agent["Windows agent"]
  node_agent["Windows agent<br/>[Program.cs]"]
  node_agentws["Cloud websocket client"]
  node_agentstate["Pairing and device state"]
  node_agentexec["Local execution<br/>[ExecuteServices.cs]"]
  node_agentsearch["Local search<br/>[SearchServices.cs]"]
  node_agentinfo["System information"]
end

subgraph group_state["Persistence and state"]
  node_memory["Memory service<br/>[memory.service.ts]"]
  node_history["Chat history"]
  node_db[("MongoDB<br/>[connectDB.ts]")]
end

node_user(("User"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_chatui
node_chatui -->|"sends chat"| node_chatroute
node_chatroute -->|"guards requests"| node_auth
node_chatroute -->|"dispatches"| node_chatcontroller
node_chatcontroller -->|"asks"| node_ai
node_chatcontroller -->|"reads and writes"| node_history
node_chatcontroller -->|"updates sessions"| node_db
node_chatcontroller -->|"sends progress"| node_wscloud
node_ai -->|"requests model"| node_modelrouter
node_ai -->|"uses guidance"| node_instructions
node_search -->|"spawns"| node_searchtool
node_authroutes -->|"authenticates"| node_auth
node_devices -->|"uses device service"| node_wscloud
node_memory -->|"persists memory"| node_db
node_history -->|"persists chats"| node_db
node_agent -->|"hosts"| node_agentws
node_agent -->|"uses state"| node_agentstate
node_agent -->|"serves commands"| node_agentexec
node_agent -->|"serves search"| node_agentsearch
node_agent -->|"streams telemetry"| node_agentinfo
node_agentws -->|"connects"| node_wscloud

click node_dashboard "https://github.com/kashif-coder404/nexus-v2/blob/main/frontend/app/(dashboard)/chat/page.tsx"
click node_chatui "https://github.com/kashif-coder404/nexus-v2/blob/main/frontend/app/components/ChatUI.tsx"
click node_chatroute "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/routes/chat.routes.ts"
click node_chatcontroller "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/controllers/chat.controller.ts"
click node_auth "https://github.com/kashif-coder404/nexus-v2/tree/main/backend/middlewares/auth"
click node_authroutes "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/routes/auth.routes.ts"
click node_devices "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/routes/device.routes.ts"
click node_wscloud "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/websocket.service.ts"
click node_ai "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/AI/askAI.ts"
click node_modelrouter "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/AI/CallAI.ts"
click node_instructions "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/AI/instructions/main.Instructions.ts"
click node_search "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/search.service.ts"
click node_searchtool "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/tools/search/search.py"
click node_exec "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/execute.service.ts"
click node_memory "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/memory.service.ts"
click node_history "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/chat.history.service.ts"
click node_db "https://github.com/kashif-coder404/nexus-v2/blob/main/backend/db/connectDB.ts"
click node_agent "https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/Program.cs"
click node_agentws "https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/WebSocketClientService.cs"
click node_agentstate "https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/DeviceStateManager.cs"
click node_agentexec "https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/ExecuteServices.cs"
click node_agentsearch "https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/SearchServices.cs"
click node_agentinfo "https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/GetSystemInfoService.cs"

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_dashboard,node_chatui,node_user toneBlue
class node_chatroute,node_chatcontroller,node_auth,node_authroutes,node_devices,node_wscloud toneAmber
class node_ai,node_modelrouter,node_instructions,node_search,node_searchtool,node_exec toneMint
class node_agent,node_agentws,node_agentstate,node_agentexec,node_agentsearch,node_agentinfo toneRose
class node_memory,node_history,node_db toneIndigo
```

## Components

### Web clients

- [Web dashboard](https://github.com/kashif-coder404/nexus-v2/blob/main/frontend/app/(dashboard)/chat/page.tsx): `frontend/app/(dashboard)/chat/page.tsx`
- [Chat interface](https://github.com/kashif-coder404/nexus-v2/blob/main/frontend/app/components/ChatUI.tsx): `frontend/app/components/ChatUI.tsx`

### Cloud backend

- [Chat routes](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/routes/chat.routes.ts): `backend/routes/chat.routes.ts`
- [Chat controller](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/controllers/chat.controller.ts): `backend/controllers/chat.controller.ts`
- [Authentication](https://github.com/kashif-coder404/nexus-v2/tree/main/backend/middlewares/auth): `backend/middlewares/auth`
- [Auth routes](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/routes/auth.routes.ts): `backend/routes/auth.routes.ts`
- [Device API](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/routes/device.routes.ts): `backend/routes/device.routes.ts`
- [Device websocket](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/websocket.service.ts): `backend/services/websocket.service.ts`

### AI and tools

- [AI orchestration](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/AI/askAI.ts): `backend/AI/askAI.ts`
- [Model providers](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/AI/CallAI.ts): `backend/AI/CallAI.ts`
- [Assistant behavior](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/AI/instructions/main.Instructions.ts): `backend/AI/instructions/main.Instructions.ts`
- [Search service](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/search.service.ts): `backend/services/search.service.ts`
- [Filesystem search](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/tools/search/search.py): `backend/tools/search/search.py`
- [Command execution](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/execute.service.ts): `backend/services/execute.service.ts`

### Windows agent

- [Windows agent](https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/Program.cs): `Local-BE-v2/Program.cs`
- [Cloud websocket client](https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/WebSocketClientService.cs): `Local-BE-v2/services/WebSocketClientService.cs`
- [Pairing and device state](https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/DeviceStateManager.cs): `Local-BE-v2/services/DeviceStateManager.cs`
- [Local execution](https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/ExecuteServices.cs): `Local-BE-v2/services/ExecuteServices.cs`
- [Local search](https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/SearchServices.cs): `Local-BE-v2/services/SearchServices.cs`
- [System information](https://github.com/kashif-coder404/nexus-v2/blob/main/Local-BE-v2/services/GetSystemInfoService.cs): `Local-BE-v2/services/GetSystemInfoService.cs`

### Persistence and state

- [Memory service](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/memory.service.ts): `backend/services/memory.service.ts`
- [Chat history](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/services/chat.history.service.ts): `backend/services/chat.history.service.ts`
- [MongoDB](https://github.com/kashif-coder404/nexus-v2/blob/main/backend/db/connectDB.ts): `backend/db/connectDB.ts`

### Other components

- **User**

## Connections

- User → Web dashboard: uses
- Web dashboard → Chat interface: renders
- Chat interface → Chat routes: sends chat
- Chat routes → Authentication: guards requests
- Chat routes → Chat controller: dispatches
- Chat controller → AI orchestration: asks
- Chat controller → Chat history: reads and writes
- Chat controller → MongoDB: updates sessions
- Chat controller → Device websocket: sends progress
- AI orchestration → Model providers: requests model
- AI orchestration → Assistant behavior: uses guidance
- Search service → Filesystem search: spawns
- Auth routes → Authentication: authenticates
- Device API → Device websocket: uses device service
- Memory service → MongoDB: persists memory
- Chat history → MongoDB: persists chats
- Windows agent → Cloud websocket client: hosts
- Windows agent → Pairing and device state: uses state
- Windows agent → Local execution: serves commands
- Windows agent → Local search: serves search
- Windows agent → System information: streams telemetry
- Cloud websocket client → Device websocket: connects