# arun18-lang/agent-platform architecture

> Architecture diagram of the GitHub repository arun18-lang/agent-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arun18-lang/agent-platform
- Repository: https://github.com/arun18-lang/agent-platform

## Overview

Nexus is an authenticated AI automation workspace. A user signs in, opens chat, submits a prompt (optionally with files or voice), and receives an answer with live tool progress; the agent routes intent, runs an OpenAI tool loop through MCP and web search, then streams results to the UI. The README documents multiple MCP integrations; local Google Workspace, WhatsApp Cloud and PowerPoint servers are shown, while several external MCP servers are configured by the manager. Voice, uploads, exports and session persistence are distinct product capabilities. Some links reflect README documentation because those implementations were not sampled.

Main entry points: [`backend/src/index.js`](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/index.js) (Express app), [`backend/src/mcp/manager.js`](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/mcp/manager.js) (MCP client manager), [`backend/src/agents/orchestrator.js`](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/agents/orchestrator.js) (Agent tool loop), [`frontend/src/ChatWorkspace.jsx`](https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/ChatWorkspace.jsx) (Chat workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Workspace UI"]
  node_app["App routing<br/>[App.jsx]"]
  node_authpage["Sign-in page<br/>[AuthPage.jsx]"]
  node_workspace["Chat workspace<br/>[ChatWorkspace.jsx]"]
  node_chat["Chat and streaming UI<br/>[ChatPanel.jsx]"]
  node_header["Workspace header"]
  node_sidebar["Tool sidebar<br/>[Sidebar.jsx]"]
  node_apihelper["API client<br/>[api.js]"]
end

subgraph group_api["Backend API"]
  node_server["Express app<br/>[index.js]"]
  node_authroute["Authentication API<br/>[auth.js]"]
  node_agentroute["Chat API<br/>[agent.js]"]
  node_toolsroute["Tools catalog API<br/>[tools.js]"]
  node_sessionsroute["Sessions API<br/>[sessions.js]"]
  node_voiceapi["Voice API<br/>[voice.js]"]
  node_exports["Generated downloads<br/>[exports.js]"]
  node_uploadparse["Upload parsing<br/>[uploadParsing.js]"]
  node_attachments["Chat attachment storage"]
end

subgraph group_agent["Agent Runtime"]
  node_orchestrator["Agent tool loop<br/>[orchestrator.js]"]
  node_intent["Intent routing<br/>[intentRouter.js]"]
  node_planner["Attachment analysis planner<br/>[analysisPlanner.js]"]
  node_uploadcontext["Uploaded data context"]
  node_downloads["Download registration"]
end

subgraph group_integrations["Tools and Integrations"]
  node_mcpmanager["MCP client manager<br/>[manager.js]"]
  node_websearch["Web search<br/>[webSearch.js]"]
  node_googlemcp["Google Workspace MCP<br/>[index.js]"]
  node_whatsappmcp["WhatsApp Cloud MCP<br/>[index.js]"]
  node_pptmcp["PowerPoint MCP<br/>[index.js]"]
end

subgraph group_state["Persistence and Voice"]
  node_mongo[("MongoDB<br/>[mongo.js]")]
  node_voiceinputs["Voice input processing<br/>[voiceInputs.js]"]
  node_speech["Speech service<br/>[sarvamSpeech.js]"]
  node_websocket["Voice WebSocket"]
  node_subscribers["Voice subscribers"]
end

node_user(("User"))
node_externalmcp{{"Configured MCP services"}}
node_speechvendor{{"Speech provider"}}

node_user -->|"opens"| node_app
node_app -->|"routes"| node_authpage
node_app -->|"protects"| node_workspace
node_user -->|"signs in"| node_authpage
node_authpage -->|"submits credentials"| node_authroute
node_authroute -->|"stores accounts"| node_mongo
node_workspace -->|"renders"| node_chat
node_workspace -->|"renders"| node_header
node_workspace -.->|"renders"| node_sidebar
node_chat -->|"builds requests"| node_apihelper
node_apihelper -.->|"calls API"| node_server
node_header -.->|"shows integrations"| node_sidebar
node_server -->|"routes requests"| node_agentroute
node_server -->|"routes requests"| node_authroute
node_server -->|"routes requests"| node_toolsroute
node_server -->|"routes requests"| node_sessionsroute
node_server -->|"routes requests"| node_voiceapi
node_server -->|"routes requests"| node_exports
node_server -->|"connects"| node_mongo
node_agentroute -->|"runs agent"| node_orchestrator
node_agentroute -->|"stores uploads"| node_attachments
node_agentroute -->|"parses uploads"| node_uploadparse
node_orchestrator -->|"classifies intent"| node_intent
node_orchestrator -->|"plans analysis"| node_planner
node_orchestrator -->|"builds context"| node_uploadcontext
node_orchestrator -->|"invokes tools"| node_mcpmanager
node_orchestrator -->|"registers files"| node_downloads
node_mcpmanager -->|"dispatches web calls"| node_websearch
node_mcpmanager -.->|"connects stdio"| node_externalmcp
node_mcpmanager -.->|"connects server"| node_googlemcp
node_mcpmanager -.->|"connects server"| node_whatsappmcp
node_mcpmanager -.->|"connects server"| node_pptmcp
node_toolsroute -->|"lists tools"| node_mcpmanager
node_sessionsroute -->|"reads and writes"| node_mongo
node_exports -->|"serves files"| node_downloads
node_server -->|"attaches socket"| node_websocket
node_voiceapi -->|"processes voice"| node_voiceinputs
node_websocket -->|"processes segments"| node_voiceinputs
node_websocket -->|"notifies listeners"| node_subscribers
node_voiceinputs -->|"transcribes speech"| node_speech
node_voiceinputs -->|"stores inputs"| node_mongo
node_speech -.->|"requests transcription"| node_speechvendor

click node_app "https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/App.jsx"
click node_authpage "https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/pages/AuthPage.jsx"
click node_workspace "https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/ChatWorkspace.jsx"
click node_chat "https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/components/ChatPanel.jsx"
click node_header "https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/components/WorkspaceHeader.jsx"
click node_sidebar "https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/components/Sidebar.jsx"
click node_apihelper "https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/api.js"
click node_server "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/index.js"
click node_authroute "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/auth.js"
click node_agentroute "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/agent.js"
click node_toolsroute "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/tools.js"
click node_sessionsroute "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/sessions.js"
click node_voiceapi "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/voice.js"
click node_exports "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/exports.js"
click node_orchestrator "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/agents/orchestrator.js"
click node_intent "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/agents/intentRouter.js"
click node_planner "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/agents/analysisPlanner.js"
click node_uploadcontext "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/uploadedDataContext.js"
click node_uploadparse "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/uploadParsing.js"
click node_attachments "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/chatAttachmentStore.js"
click node_downloads "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/generatedFileDownloads.js"
click node_mcpmanager "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/mcp/manager.js"
click node_websearch "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/tools/webSearch.js"
click node_googlemcp "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/mcp/google-workspace-mcp/index.js"
click node_whatsappmcp "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/mcp/whatsapp-cloud-mcp/index.js"
click node_pptmcp "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/mcp/rich-ppt-mcp/index.js"
click node_mongo "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/db/mongo.js"
click node_voiceinputs "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/voiceInputs.js"
click node_speech "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/sarvamSpeech.js"
click node_websocket "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/voice/attachVoiceWebSocket.js"
click node_subscribers "https://github.com/arun18-lang/agent-platform/blob/main/backend/src/voice/voiceSubscribers.js"

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_app,node_authpage,node_workspace,node_chat,node_header,node_sidebar,node_apihelper,node_user toneBlue
class node_server,node_authroute,node_agentroute,node_toolsroute,node_sessionsroute,node_voiceapi,node_exports,node_uploadparse,node_attachments toneAmber
class node_orchestrator,node_intent,node_planner,node_uploadcontext,node_downloads toneMint
class node_mcpmanager,node_websearch,node_googlemcp,node_whatsappmcp,node_pptmcp toneRose
class node_mongo,node_voiceinputs,node_speech,node_websocket,node_subscribers,node_externalmcp,node_speechvendor toneIndigo
```

## Components

### Workspace UI

- [App routing](https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in page](https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/pages/AuthPage.jsx): `frontend/src/pages/AuthPage.jsx`
- [Chat workspace](https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/ChatWorkspace.jsx): `frontend/src/ChatWorkspace.jsx`
- [Chat and streaming UI](https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/components/ChatPanel.jsx): `frontend/src/components/ChatPanel.jsx`
- [Workspace header](https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/components/WorkspaceHeader.jsx): `frontend/src/components/WorkspaceHeader.jsx`
- [Tool sidebar](https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/components/Sidebar.jsx): `frontend/src/components/Sidebar.jsx`
- [API client](https://github.com/arun18-lang/agent-platform/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Backend API

- [Express app](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/index.js): `backend/src/index.js`
- [Authentication API](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/auth.js): `backend/src/routes/auth.js`
- [Chat API](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/agent.js): `backend/src/routes/agent.js`
- [Tools catalog API](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/tools.js): `backend/src/routes/tools.js`
- [Sessions API](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/sessions.js): `backend/src/routes/sessions.js`
- [Voice API](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/voice.js): `backend/src/routes/voice.js`
- [Generated downloads](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/routes/exports.js): `backend/src/routes/exports.js`
- [Upload parsing](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/uploadParsing.js): `backend/src/services/uploadParsing.js`
- [Chat attachment storage](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/chatAttachmentStore.js): `backend/src/services/chatAttachmentStore.js`

### Agent Runtime

- [Agent tool loop](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/agents/orchestrator.js): `backend/src/agents/orchestrator.js`
- [Intent routing](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/agents/intentRouter.js): `backend/src/agents/intentRouter.js`
- [Attachment analysis planner](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/agents/analysisPlanner.js): `backend/src/agents/analysisPlanner.js`
- [Uploaded data context](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/uploadedDataContext.js): `backend/src/services/uploadedDataContext.js`
- [Download registration](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/generatedFileDownloads.js): `backend/src/services/generatedFileDownloads.js`

### Tools and Integrations

- [MCP client manager](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/mcp/manager.js): `backend/src/mcp/manager.js`
- [Web search](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/tools/webSearch.js): `backend/src/tools/webSearch.js`
- [Google Workspace MCP](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/mcp/google-workspace-mcp/index.js): `backend/src/mcp/google-workspace-mcp/index.js`
- [WhatsApp Cloud MCP](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/mcp/whatsapp-cloud-mcp/index.js): `backend/src/mcp/whatsapp-cloud-mcp/index.js`
- [PowerPoint MCP](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/mcp/rich-ppt-mcp/index.js): `backend/src/mcp/rich-ppt-mcp/index.js`

### Persistence and Voice

- [MongoDB](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/db/mongo.js): `backend/src/db/mongo.js`
- [Voice input processing](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/voiceInputs.js): `backend/src/services/voiceInputs.js`
- [Speech service](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/services/sarvamSpeech.js): `backend/src/services/sarvamSpeech.js`
- [Voice WebSocket](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/voice/attachVoiceWebSocket.js): `backend/src/voice/attachVoiceWebSocket.js`
- [Voice subscribers](https://github.com/arun18-lang/agent-platform/blob/main/backend/src/voice/voiceSubscribers.js): `backend/src/voice/voiceSubscribers.js`

### Other components

- **User**
- **Configured MCP services**
- **Speech provider**

## Connections

- User → App routing: opens (evidence: `frontend/src/App.jsx`)
- App routing → Sign-in page: routes (evidence: `frontend/src/App.jsx`)
- App routing → Chat workspace: protects (evidence: `frontend/src/App.jsx`)
- User → Sign-in page: signs in (evidence: `frontend/src/pages/AuthPage.jsx`)
- Sign-in page → Authentication API: submits credentials (evidence: `frontend/src/pages/AuthPage.jsx`)
- Authentication API → MongoDB: stores accounts (evidence: `backend/src/routes/auth.js`)
- Chat workspace → Chat and streaming UI: renders (evidence: `frontend/src/ChatWorkspace.jsx`)
- Chat workspace → Workspace header: renders (evidence: `frontend/src/ChatWorkspace.jsx`)
- Chat workspace → Tool sidebar: renders
- Chat and streaming UI → API client: builds requests (evidence: `frontend/src/components/ChatPanel.jsx`)
- API client → Express app: calls API
- Workspace header → Tool sidebar: shows integrations
- Express app → Chat API: routes requests (evidence: `backend/src/index.js`)
- Express app → Authentication API: routes requests (evidence: `backend/src/index.js`)
- Express app → Tools catalog API: routes requests (evidence: `backend/src/index.js`)
- Express app → Sessions API: routes requests (evidence: `backend/src/index.js`)
- Express app → Voice API: routes requests (evidence: `backend/src/index.js`)
- Express app → Generated downloads: routes requests (evidence: `backend/src/index.js`)
- Express app → MongoDB: connects (evidence: `backend/src/index.js`)
- Chat API → Agent tool loop: runs agent (evidence: `backend/src/routes/agent.js`)
- Chat API → Chat attachment storage: stores uploads (evidence: `backend/src/routes/agent.js`)
- Chat API → Upload parsing: parses uploads (evidence: `backend/src/routes/agent.js`)
- Agent tool loop → Intent routing: classifies intent (evidence: `backend/src/agents/orchestrator.js`)
- Agent tool loop → Attachment analysis planner: plans analysis (evidence: `backend/src/agents/orchestrator.js`)
- Agent tool loop → Uploaded data context: builds context (evidence: `backend/src/agents/orchestrator.js`)
- Agent tool loop → MCP client manager: invokes tools (evidence: `backend/src/agents/orchestrator.js`)
- Agent tool loop → Download registration: registers files (evidence: `backend/src/agents/orchestrator.js`)
- MCP client manager → Web search: dispatches web calls (evidence: `backend/src/mcp/manager.js`)
- MCP client manager → Configured MCP services: connects stdio (evidence: `README.md`)
- MCP client manager → Google Workspace MCP: connects server (evidence: `README.md`)
- MCP client manager → WhatsApp Cloud MCP: connects server (evidence: `README.md`)
- MCP client manager → PowerPoint MCP: connects server (evidence: `README.md`)
- Tools catalog API → MCP client manager: lists tools (evidence: `backend/src/routes/tools.js`)
- Sessions API → MongoDB: reads and writes (evidence: `backend/src/routes/sessions.js`)
- Generated downloads → Download registration: serves files (evidence: `backend/src/routes/exports.js`)
- Express app → Voice WebSocket: attaches socket (evidence: `backend/src/index.js`)
- Voice API → Voice input processing: processes voice (evidence: `backend/src/routes/voice.js`)
- Voice WebSocket → Voice input processing: processes segments (evidence: `backend/src/voice/attachVoiceWebSocket.js`)
- Voice WebSocket → Voice subscribers: notifies listeners (evidence: `backend/src/voice/attachVoiceWebSocket.js`)
- Voice input processing → Speech service: transcribes speech (evidence: `backend/src/services/voiceInputs.js`)
- Voice input processing → MongoDB: stores inputs (evidence: `backend/src/services/voiceInputs.js`)
- Speech service → Speech provider: requests transcription
