# n00bvn/canvasmcpclient architecture

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

- Interactive diagram: https://gitdiagram.com/n00bvn/canvasmcpclient
- Repository: https://github.com/n00bvn/canvasmcpclient

## Overview

Canvas MCP Client is a self-hosted infinite-canvas dashboard for creating and arranging configurable widgets, connecting widgets to MCP tools and AI providers, and persisting dashboards and configurations. The principal workflow runs from the canvas and widget renderer through frontend API services to FastAPI routes and database-backed state; optional MCP and AI integrations provide tool execution and conversion. The README also documents templates, import/export, and server-directory discovery. Some frontend-to-API links and unsampled capabilities are documented but their exact runtime wiring is not shown in the excerpts.

Main entry points: [`backend/database.py`](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/database.py) (Application Database), [`backend/main.py`](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/main.py) (FastAPI App), [`backend/routers/ai_chat.py`](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/ai_chat.py) (AI Chat), [`backend/routers/widget_connections.py`](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/widget_connections.py) (Widget Connections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_canvas["Canvas Workspace"]
  node_canvas_view["Canvas Workspace<br/>[Canvas.tsx]"]
end

subgraph group_widgets["Widget System"]
  node_widget_frontend["Widget Renderer<br/>[WidgetRenderer.tsx]"]
  node_widget_engine["Blueprint Engine"]
  node_widget_builder["Widget Builder"]
  node_widget_connections["Widget Connections"]
  node_connection_panel["Connection Panel"]
end

subgraph group_backend["API and Persistence"]
  node_dashboard_api["Dashboard API<br/>[dashboards.py]"]
  node_widget_api["Widget API<br/>[widgets.py]"]
  node_api_client["Frontend API<br/>[api.ts]"]
  node_app_router["FastAPI App<br/>[main.py]"]
  node_database[("Application Database<br/>[database.py]")]
end

subgraph group_integrations["AI and MCP"]
  node_mcp_config["MCP Server Config<br/>[mcp_servers.py]"]
  node_mcp_runtime["MCP Runtime<br/>[mcp_service.py]"]
  node_mcp_directory["MCP Directory<br/>[mcp_directory.py]"]
  node_mcp_registry["Registry Sync"]
  node_ai_chat["AI Chat<br/>[ai_chat.py]"]
  node_conversion["AI Data Conversion"]
end

subgraph group_configuration["Configuration and Templates"]
  node_ai_config["AI Configuration<br/>[ai_configs.py]"]
  node_credential_crypto["Credential Encryption"]
  node_blueprints["Widget Blueprints"]
  node_dashboard_templates["Dashboard Import Export"]
end

node_user(("Dashboard User"))
node_mcp_servers_ext{{"MCP Servers"}}
node_ai_providers{{"AI Providers"}}

node_user -->|"arranges workspace"| node_canvas_view
node_canvas_view -.->|"loads dashboards"| node_dashboard_api
node_canvas_view -.->|"renders widgets"| node_widget_frontend
node_widget_frontend -.->|"renders blueprint"| node_widget_engine
node_widget_engine -.->|"loads widget data"| node_widget_api
node_widget_builder -.->|"creates widgets"| node_blueprints
node_connection_panel -.->|"manages connections"| node_widget_connections
node_api_client -.->|"sends API requests"| node_app_router
node_app_router -->|"registers routes"| node_dashboard_api
node_app_router -->|"registers routes"| node_widget_api
node_app_router -->|"registers routes"| node_widget_connections
node_app_router -->|"registers routes"| node_mcp_config
node_app_router -->|"registers routes"| node_mcp_directory
node_app_router -->|"initializes storage"| node_database
node_dashboard_api -->|"reads and writes"| node_database
node_widget_api -->|"reads and writes"| node_database
node_widget_connections -->|"reads and writes"| node_database
node_widget_connections -->|"converts widget data"| node_conversion
node_conversion -->|"loads configuration"| node_database
node_conversion -->|"decrypts credentials"| node_credential_crypto
node_mcp_config -->|"persists server configs"| node_database
node_mcp_config -->|"manages connections"| node_mcp_runtime
node_mcp_runtime -->|"connects to servers"| node_mcp_servers_ext
node_mcp_directory -->|"reads directory data"| node_database
node_mcp_registry -->|"syncs registry data"| node_database
node_ai_chat -->|"loads AI config"| node_database
node_ai_chat -->|"decrypts credentials"| node_credential_crypto
node_ai_chat -->|"executes tool calls"| node_mcp_runtime
node_ai_chat -.->|"requests completions"| node_ai_providers
node_ai_config -->|"stores configurations"| node_database
node_ai_config -->|"encrypts credentials"| node_credential_crypto
node_dashboard_templates -.->|"imports and exports"| node_dashboard_api
node_user -.->|"discovers servers"| node_mcp_directory

click node_canvas_view "https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Canvas/Canvas.tsx"
click node_dashboard_api "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/dashboards.py"
click node_widget_api "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/widgets.py"
click node_widget_frontend "https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Widgets/WidgetRenderer.tsx"
click node_widget_engine "https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Widgets/UniversalWidgetEngine/UniversalWidgetEngine.tsx"
click node_widget_builder "https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Modals/WidgetBuilderModal.tsx"
click node_widget_connections "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/widget_connections.py"
click node_connection_panel "https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Panels/ConnectionPanel.tsx"
click node_api_client "https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/services/api.ts"
click node_app_router "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/main.py"
click node_database "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/database.py"
click node_mcp_config "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/mcp_servers.py"
click node_mcp_runtime "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/services/mcp_service.py"
click node_mcp_directory "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/mcp_directory.py"
click node_mcp_registry "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/services/mcp_registry_service.py"
click node_ai_chat "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/ai_chat.py"
click node_ai_config "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/ai_configs.py"
click node_credential_crypto "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/services/encryption_service.py"
click node_conversion "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/services/ai_conversion_service.py"
click node_blueprints "https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/widget_blueprints.py"
click node_dashboard_templates "https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Modals/DashboardImportExportModal.tsx"

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_canvas_view,node_user toneBlue
class node_widget_frontend,node_widget_engine,node_widget_builder,node_widget_connections,node_connection_panel toneAmber
class node_dashboard_api,node_widget_api,node_api_client,node_app_router,node_database,node_mcp_servers_ext toneMint
class node_mcp_config,node_mcp_runtime,node_mcp_directory,node_mcp_registry,node_ai_chat,node_conversion toneRose
class node_ai_config,node_credential_crypto,node_blueprints,node_dashboard_templates,node_ai_providers toneIndigo
```

## Components

### Canvas Workspace

- [Canvas Workspace](https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Canvas/Canvas.tsx): `frontend/src/components/Canvas/Canvas.tsx`

### Widget System

- [Widget Renderer](https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Widgets/WidgetRenderer.tsx): `frontend/src/components/Widgets/WidgetRenderer.tsx`
- [Blueprint Engine](https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Widgets/UniversalWidgetEngine/UniversalWidgetEngine.tsx): `frontend/src/components/Widgets/UniversalWidgetEngine/UniversalWidgetEngine.tsx`
- [Widget Builder](https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Modals/WidgetBuilderModal.tsx): `frontend/src/components/Modals/WidgetBuilderModal.tsx`
- [Widget Connections](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/widget_connections.py): `backend/routers/widget_connections.py`
- [Connection Panel](https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Panels/ConnectionPanel.tsx): `frontend/src/components/Panels/ConnectionPanel.tsx`

### API and Persistence

- [Dashboard API](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/dashboards.py): `backend/routers/dashboards.py`
- [Widget API](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/widgets.py): `backend/routers/widgets.py`
- [Frontend API](https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [FastAPI App](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/main.py): `backend/main.py`
- [Application Database](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/database.py): `backend/database.py`

### AI and MCP

- [MCP Server Config](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/mcp_servers.py): `backend/routers/mcp_servers.py`
- [MCP Runtime](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/services/mcp_service.py): `backend/services/mcp_service.py`
- [MCP Directory](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/mcp_directory.py): `backend/routers/mcp_directory.py`
- [Registry Sync](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/services/mcp_registry_service.py): `backend/services/mcp_registry_service.py`
- [AI Chat](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/ai_chat.py): `backend/routers/ai_chat.py`
- [AI Data Conversion](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/services/ai_conversion_service.py): `backend/services/ai_conversion_service.py`

### Configuration and Templates

- [AI Configuration](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/ai_configs.py): `backend/routers/ai_configs.py`
- [Credential Encryption](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/services/encryption_service.py): `backend/services/encryption_service.py`
- [Widget Blueprints](https://github.com/n00bvn/canvasmcpclient/blob/production/backend/routers/widget_blueprints.py): `backend/routers/widget_blueprints.py`
- [Dashboard Import Export](https://github.com/n00bvn/canvasmcpclient/blob/production/frontend/src/components/Modals/DashboardImportExportModal.tsx): `frontend/src/components/Modals/DashboardImportExportModal.tsx`

### Other components

- **Dashboard User**
- **MCP Servers**
- **AI Providers**

## Connections

- Dashboard User → Canvas Workspace: arranges workspace
- Canvas Workspace → Dashboard API: loads dashboards
- Canvas Workspace → Widget Renderer: renders widgets
- Widget Renderer → Blueprint Engine: renders blueprint
- Blueprint Engine → Widget API: loads widget data
- Widget Builder → Widget Blueprints: creates widgets
- Connection Panel → Widget Connections: manages connections
- Frontend API → FastAPI App: sends API requests
- FastAPI App → Dashboard API: registers routes (evidence: `backend/main.py`)
- FastAPI App → Widget API: registers routes (evidence: `backend/main.py`)
- FastAPI App → Widget Connections: registers routes (evidence: `backend/main.py`)
- FastAPI App → MCP Server Config: registers routes (evidence: `backend/main.py`)
- FastAPI App → MCP Directory: registers routes (evidence: `backend/main.py`)
- FastAPI App → Application Database: initializes storage (evidence: `backend/main.py`)
- Dashboard API → Application Database: reads and writes (evidence: `backend/routers/dashboards.py`)
- Widget API → Application Database: reads and writes (evidence: `backend/routers/widgets.py`)
- Widget Connections → Application Database: reads and writes (evidence: `backend/routers/widget_connections.py`)
- Widget Connections → AI Data Conversion: converts widget data (evidence: `backend/routers/widget_connections.py`)
- AI Data Conversion → Application Database: loads configuration (evidence: `backend/services/ai_conversion_service.py`)
- AI Data Conversion → Credential Encryption: decrypts credentials (evidence: `backend/services/ai_conversion_service.py`)
- MCP Server Config → Application Database: persists server configs (evidence: `backend/routers/mcp_servers.py`)
- MCP Server Config → MCP Runtime: manages connections (evidence: `backend/routers/mcp_servers.py`)
- MCP Runtime → MCP Servers: connects to servers (evidence: `backend/services/mcp_service.py`)
- MCP Directory → Application Database: reads directory data (evidence: `backend/routers/mcp_directory.py`)
- Registry Sync → Application Database: syncs registry data (evidence: `backend/services/mcp_registry_service.py`)
- AI Chat → Application Database: loads AI config (evidence: `backend/routers/ai_chat.py`)
- AI Chat → Credential Encryption: decrypts credentials (evidence: `backend/routers/ai_chat.py`)
- AI Chat → MCP Runtime: executes tool calls (evidence: `backend/routers/ai_chat.py`)
- AI Chat → AI Providers: requests completions
- AI Configuration → Application Database: stores configurations (evidence: `backend/routers/ai_configs.py`)
- AI Configuration → Credential Encryption: encrypts credentials (evidence: `backend/routers/ai_configs.py`)
- Dashboard Import Export → Dashboard API: imports and exports
- Dashboard User → MCP Directory: discovers servers