# pranavubarhande/vivexy architecture

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

- Interactive diagram: https://gitdiagram.com/pranavubarhande/vivexy
- Repository: https://github.com/pranavubarhande/vivexy

## Overview

Vivexy is an AI operating system for professional teams, delivered through web and desktop clients backed by a Flask service and shared agent runtime. A user configures an agent, submits a chat or document task, and receives streamed answers, citations or generated artifacts; the platform also supports domain tools, RAG, scheduled runs, and team controls. The sampled sources show scheduled-task API dispatch and desktop MCP handling directly. Other major capabilities are retained from the README, but their internal call paths were not sampled, so those links are marked unverified.

Main entry points: [`packages/agents-core/src/agents_core/business_logic/chat.py`](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/chat.py) (Chat orchestration), [`packages/agents-core/src/agents_core/models/base.py`](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/models/base.py) (Application database), [`packages/agents-core/src/agents_core/business_logic/scheduled_tasks.py`](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/scheduled_tasks.py) (Schedule management), [`apps/agents-service/app.py`](https://github.com/pranavubarhande/vivexy/blob/main/apps/agents-service/app.py) (Flask API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_web["Web workspace<br/>[agentic-chat.tsx]"]
  node_desktop["Desktop app<br/>[ipc-handlers.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_desktop_mcp["Desktop MCP manager<br/>[mcp-manager.ts]"]
end

subgraph group_api["Service API"]
  node_api["Flask API<br/>[app.py]"]
  node_chat_routes["Chat and agent routes<br/>[chat.py]"]
  node_analysis_routes["Document analysis routes"]
  node_rag_routes["Document and RAG routes<br/>[rag.py]"]
  node_scheduled_routes["Scheduled-task routes<br/>[scheduled_tasks.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_chat_logic["Chat orchestration<br/>[chat.py]"]
  node_agent_config["Agent configuration<br/>[config.py]"]
  node_streaming["Streaming responses<br/>[streaming.py]"]
  node_queue["Job queues<br/>[dispatcher.py]"]
  node_worker["Chat workers<br/>[consumer.py]"]
end

subgraph group_domain["Knowledge and tools"]
  node_rag["Retrieval service<br/>[rag_service.py]"]
  node_file_processing["Document processing<br/>[file_processor.py]"]
  node_domain_tools["Domain tools"]
  node_skills_mcp["Skills and MCP<br/>[mcp_client.py]"]
end

subgraph group_operations["Team operations"]
  node_scheduled_logic["Schedule management<br/>[scheduled_tasks.py]"]
  node_scheduler["Task scheduler<br/>[scheduler.py]"]
  node_task_runner["Scheduled task runner"]
  node_teams["Teams and policy<br/>[teams.py]"]
  node_billing["Billing and usage<br/>[billing.py]"]
  node_database[("Application database<br/>[base.py]")]
end

node_user(("Professional user"))

node_user -.->|"uses"| node_web
node_user -.->|"uses"| node_desktop
node_web -.->|"requests"| node_api
node_auth -->|"authenticates"| node_api
node_api -.->|"routes requests"| node_chat_routes
node_chat_routes -.->|"delegates"| node_chat_logic
node_chat_logic -.->|"configures agents"| node_agent_config
node_chat_logic -.->|"dispatches jobs"| node_queue
node_worker -.->|"runs jobs"| node_chat_logic
node_chat_logic -.->|"streams results"| node_streaming
node_chat_logic -.->|"retrieves context"| node_rag
node_chat_logic -.->|"invokes tools"| node_domain_tools
node_chat_logic -.->|"loads skills"| node_skills_mcp
node_rag_routes -.->|"processes uploads"| node_file_processing
node_rag_routes -.->|"retrieves documents"| node_rag
node_analysis_routes -.->|"analyzes documents"| node_file_processing
node_scheduled_routes -->|"calls task logic"| node_scheduled_logic
node_scheduled_logic -->|"dispatches runs"| node_queue
node_scheduler -.->|"triggers runs"| node_task_runner
node_task_runner -.->|"runs prompt"| node_chat_logic
node_scheduled_logic -->|"stores schedules"| node_database
node_chat_logic -.->|"stores conversations"| node_database
node_file_processing -.->|"stores document data"| node_database
node_teams -.->|"stores team state"| node_database
node_billing -.->|"records usage"| node_database
node_desktop -->|"starts MCP"| node_desktop_mcp
node_desktop_mcp -.->|"proxies tool calls"| node_skills_mcp

click node_web "https://github.com/pranavubarhande/vivexy/blob/main/packages/core/src/components/chat/agentic-chat.tsx"
click node_desktop "https://github.com/pranavubarhande/vivexy/blob/main/packages/desktop/src/ipc-handlers.ts"
click node_auth "https://github.com/pranavubarhande/vivexy/blob/main/packages/core/src/services/auth.service.ts"
click node_api "https://github.com/pranavubarhande/vivexy/blob/main/apps/agents-service/app.py"
click node_chat_routes "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/routes/chat.py"
click node_analysis_routes "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/routes/document_analyses.py"
click node_rag_routes "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/routes/rag.py"
click node_scheduled_routes "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/routes/scheduled_tasks.py"
click node_chat_logic "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/chat.py"
click node_agent_config "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/agents/config.py"
click node_streaming "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/streaming.py"
click node_queue "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/worker/dispatcher.py"
click node_worker "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/worker/consumer.py"
click node_rag "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/services/rag_service.py"
click node_file_processing "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/services/file_processor.py"
click node_domain_tools "https://github.com/pranavubarhande/vivexy/tree/main/packages/agents-core/src/agents_core/tools"
click node_skills_mcp "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/agents/mcp_client.py"
click node_scheduled_logic "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/scheduled_tasks.py"
click node_scheduler "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/worker/scheduler.py"
click node_task_runner "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/worker/scheduled_task_runner.py"
click node_teams "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/teams.py"
click node_billing "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/billing.py"
click node_database "https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/models/base.py"
click node_desktop_mcp "https://github.com/pranavubarhande/vivexy/blob/main/packages/desktop/src/tools/mcp-manager.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_web,node_desktop,node_auth,node_desktop_mcp,node_user toneBlue
class node_api,node_chat_routes,node_analysis_routes,node_rag_routes,node_scheduled_routes toneAmber
class node_chat_logic,node_agent_config,node_streaming,node_queue,node_worker toneMint
class node_rag,node_file_processing,node_domain_tools,node_skills_mcp toneRose
class node_scheduled_logic,node_scheduler,node_task_runner,node_teams,node_billing,node_database toneIndigo
```

## Components

### User clients

- [Web workspace](https://github.com/pranavubarhande/vivexy/blob/main/packages/core/src/components/chat/agentic-chat.tsx): `packages/core/src/components/chat/agentic-chat.tsx`
- [Desktop app](https://github.com/pranavubarhande/vivexy/blob/main/packages/desktop/src/ipc-handlers.ts): `packages/desktop/src/ipc-handlers.ts`
- [Authentication](https://github.com/pranavubarhande/vivexy/blob/main/packages/core/src/services/auth.service.ts): `packages/core/src/services/auth.service.ts`
- [Desktop MCP manager](https://github.com/pranavubarhande/vivexy/blob/main/packages/desktop/src/tools/mcp-manager.ts): `packages/desktop/src/tools/mcp-manager.ts`

### Service API

- [Flask API](https://github.com/pranavubarhande/vivexy/blob/main/apps/agents-service/app.py): `apps/agents-service/app.py`
- [Chat and agent routes](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/routes/chat.py): `packages/agents-core/src/agents_core/routes/chat.py`
- [Document analysis routes](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/routes/document_analyses.py): `packages/agents-core/src/agents_core/routes/document_analyses.py`
- [Document and RAG routes](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/routes/rag.py): `packages/agents-core/src/agents_core/routes/rag.py`
- [Scheduled-task routes](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/routes/scheduled_tasks.py): `packages/agents-core/src/agents_core/routes/scheduled_tasks.py`

### Agent runtime

- [Chat orchestration](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/chat.py): `packages/agents-core/src/agents_core/business_logic/chat.py`
- [Agent configuration](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/agents/config.py): `packages/agents-core/src/agents_core/agents/config.py`
- [Streaming responses](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/streaming.py): `packages/agents-core/src/agents_core/business_logic/streaming.py`
- [Job queues](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/worker/dispatcher.py): `packages/agents-core/src/agents_core/worker/dispatcher.py`
- [Chat workers](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/worker/consumer.py): `packages/agents-core/src/agents_core/worker/consumer.py`

### Knowledge and tools

- [Retrieval service](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/services/rag_service.py): `packages/agents-core/src/agents_core/services/rag_service.py`
- [Document processing](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/services/file_processor.py): `packages/agents-core/src/agents_core/services/file_processor.py`
- [Domain tools](https://github.com/pranavubarhande/vivexy/tree/main/packages/agents-core/src/agents_core/tools): `packages/agents-core/src/agents_core/tools`
- [Skills and MCP](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/agents/mcp_client.py): `packages/agents-core/src/agents_core/agents/mcp_client.py`

### Team operations

- [Schedule management](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/scheduled_tasks.py): `packages/agents-core/src/agents_core/business_logic/scheduled_tasks.py`
- [Task scheduler](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/worker/scheduler.py): `packages/agents-core/src/agents_core/worker/scheduler.py`
- [Scheduled task runner](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/worker/scheduled_task_runner.py): `packages/agents-core/src/agents_core/worker/scheduled_task_runner.py`
- [Teams and policy](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/teams.py): `packages/agents-core/src/agents_core/business_logic/teams.py`
- [Billing and usage](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/business_logic/billing.py): `packages/agents-core/src/agents_core/business_logic/billing.py`
- [Application database](https://github.com/pranavubarhande/vivexy/blob/main/packages/agents-core/src/agents_core/models/base.py): `packages/agents-core/src/agents_core/models/base.py`

### Other components

- **Professional user**

## Connections

- Professional user → Web workspace: uses
- Professional user → Desktop app: uses
- Web workspace → Flask API: requests
- Authentication → Flask API: authenticates (evidence: `packages/core/src/services/auth.service.ts`)
- Flask API → Chat and agent routes: routes requests
- Chat and agent routes → Chat orchestration: delegates
- Chat orchestration → Agent configuration: configures agents
- Chat orchestration → Job queues: dispatches jobs
- Chat workers → Chat orchestration: runs jobs
- Chat orchestration → Streaming responses: streams results
- Chat orchestration → Retrieval service: retrieves context
- Chat orchestration → Domain tools: invokes tools
- Chat orchestration → Skills and MCP: loads skills
- Document and RAG routes → Document processing: processes uploads
- Document and RAG routes → Retrieval service: retrieves documents
- Document analysis routes → Document processing: analyzes documents
- Scheduled-task routes → Schedule management: calls task logic (evidence: `packages/agents-core/src/agents_core/routes/scheduled_tasks.py`)
- Schedule management → Job queues: dispatches runs (evidence: `packages/agents-core/src/agents_core/business_logic/scheduled_tasks.py`)
- Task scheduler → Scheduled task runner: triggers runs
- Scheduled task runner → Chat orchestration: runs prompt
- Schedule management → Application database: stores schedules (evidence: `packages/agents-core/src/agents_core/business_logic/scheduled_tasks.py`)
- Chat orchestration → Application database: stores conversations
- Document processing → Application database: stores document data
- Teams and policy → Application database: stores team state
- Billing and usage → Application database: records usage
- Desktop app → Desktop MCP manager: starts MCP (evidence: `packages/desktop/src/ipc-handlers.ts`)
- Desktop MCP manager → Skills and MCP: proxies tool calls
