# tct68/claudex architecture

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

- Interactive diagram: https://gitdiagram.com/tct68/claudex
- Repository: https://github.com/tct68/claudex

## Overview

ClaudeX is a visual manager for a project’s Claude Code workspace. Users initialize a `.claude` workspace, start the local server, then manage commands, skills, hooks, agents, MCP servers, and workspace backups in the web UI. The API also supports template operations and Claude CLI tests; the registry exposes discovered workspace assets. The source excerpts establish server and service calls, but do not show how individual pages invoke the API, so those links are omitted. The README documents live reload and the vision-to-UI integration.

Main entry points: [`src/web/src/App.jsx`](https://github.com/tct68/claudex/blob/master/src/web/src/App.jsx) (Web app shell), [`src/server/index.js`](https://github.com/tct68/claudex/blob/master/src/server/index.js) (HTTP server), [`bin/cli.js`](https://github.com/tct68/claudex/blob/master/bin/cli.js) (ClaudeX CLI), [`src/server/routes/api.js`](https://github.com/tct68/claudex/blob/master/src/server/routes/api.js) (Workspace API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and UI"]
  node_cli["ClaudeX CLI<br/>[cli.js]"]
  node_web_app["Web app shell<br/>[App.jsx]"]
  node_layout["UI layout<br/>[Layout.jsx]"]
end

subgraph group_management["Workspace management"]
  node_workspace_setup["Workspace setup<br/>[workspace.js]"]
  node_commands["Commands<br/>[CommandsPage.jsx]"]
  node_skills["Skills<br/>[SkillsPage.jsx]"]
  node_hooks["Hooks<br/>[HooksPage.jsx]"]
  node_agents["Agents<br/>[AgentsPage.jsx]"]
  node_mcp_management["MCP management<br/>[MCPServersPage.jsx]"]
  node_import_export["Import and export"]
  node_template_preview["Template preview"]
  node_markdown_preview["Markdown preview"]
end

subgraph group_runtime["Server runtime"]
  node_api["Workspace API<br/>[api.js]"]
  node_server["HTTP server<br/>[index.js]"]
  node_workspace_info["Workspace discovery<br/>[workspace.js]"]
  node_registry_routes["Registry API<br/>[registry.js]"]
  node_agent_registry["Asset registry<br/>[agent-registry.js]"]
end

subgraph group_integrations["Integrations"]
  node_claude_service["Claude CLI service<br/>[claude.js]"]
  node_claude_cli["Claude Code CLI"]
  node_vision_server["Vision-to-UI server<br/>[index.js]"]
end

node_developer(("Developer"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"initializes workspace"| node_workspace_setup
node_cli -->|"starts server"| node_server
node_developer -->|"manages workspace"| node_web_app
node_web_app -->|"renders"| node_layout
node_web_app -->|"routes to"| node_commands
node_web_app -->|"routes to"| node_skills
node_web_app -->|"routes to"| node_hooks
node_web_app -->|"routes to"| node_agents
node_web_app -->|"routes to"| node_mcp_management
node_web_app -->|"routes to"| node_import_export
node_template_preview -->|"renders content"| node_markdown_preview
node_server -->|"mounts routes"| node_api
node_server -->|"mounts routes"| node_registry_routes
node_server -->|"reads workspace"| node_workspace_info
node_server -->|"checks installation"| node_claude_service
node_api -->|"gets workspace info"| node_workspace_info
node_api -->|"tests commands"| node_claude_service
node_registry_routes -->|"discovers assets"| node_agent_registry
node_claude_service -->|"spawns process"| node_claude_cli
node_developer -.->|"uses MCP integration"| node_vision_server

click node_cli "https://github.com/tct68/claudex/blob/master/bin/cli.js"
click node_workspace_setup "https://github.com/tct68/claudex/blob/master/src/server/services/workspace.js"
click node_web_app "https://github.com/tct68/claudex/blob/master/src/web/src/App.jsx"
click node_layout "https://github.com/tct68/claudex/blob/master/src/web/src/components/Layout.jsx"
click node_commands "https://github.com/tct68/claudex/blob/master/src/web/src/pages/CommandsPage.jsx"
click node_skills "https://github.com/tct68/claudex/blob/master/src/web/src/pages/SkillsPage.jsx"
click node_hooks "https://github.com/tct68/claudex/blob/master/src/web/src/pages/HooksPage.jsx"
click node_agents "https://github.com/tct68/claudex/blob/master/src/web/src/pages/AgentsPage.jsx"
click node_mcp_management "https://github.com/tct68/claudex/blob/master/src/web/src/pages/MCPServersPage.jsx"
click node_import_export "https://github.com/tct68/claudex/blob/master/src/web/src/pages/ImportExportPage.jsx"
click node_template_preview "https://github.com/tct68/claudex/blob/master/src/web/src/components/TemplatePreviewModal.jsx"
click node_markdown_preview "https://github.com/tct68/claudex/blob/master/src/web/src/components/MarkdownPreview.jsx"
click node_api "https://github.com/tct68/claudex/blob/master/src/server/routes/api.js"
click node_server "https://github.com/tct68/claudex/blob/master/src/server/index.js"
click node_workspace_info "https://github.com/tct68/claudex/blob/master/src/server/services/workspace.js"
click node_registry_routes "https://github.com/tct68/claudex/blob/master/src/server/routes/registry.js"
click node_agent_registry "https://github.com/tct68/claudex/blob/master/src/server/services/agent-registry.js"
click node_claude_service "https://github.com/tct68/claudex/blob/master/src/server/services/claude.js"
click node_vision_server "https://github.com/tct68/claudex/blob/master/src/mcp-servers/vision-ui/index.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_cli,node_web_app,node_layout toneBlue
class node_workspace_setup,node_commands,node_skills,node_hooks,node_agents,node_mcp_management,node_import_export,node_template_preview,node_markdown_preview toneAmber
class node_api,node_server,node_workspace_info,node_registry_routes,node_agent_registry toneMint
class node_claude_service,node_claude_cli,node_vision_server toneRose
class node_developer toneIndigo
```

## Components

### Entry and UI

- [ClaudeX CLI](https://github.com/tct68/claudex/blob/master/bin/cli.js): `bin/cli.js`
- [Web app shell](https://github.com/tct68/claudex/blob/master/src/web/src/App.jsx): `src/web/src/App.jsx`
- [UI layout](https://github.com/tct68/claudex/blob/master/src/web/src/components/Layout.jsx): `src/web/src/components/Layout.jsx`

### Workspace management

- [Workspace setup](https://github.com/tct68/claudex/blob/master/src/server/services/workspace.js): `src/server/services/workspace.js`
- [Commands](https://github.com/tct68/claudex/blob/master/src/web/src/pages/CommandsPage.jsx): `src/web/src/pages/CommandsPage.jsx`
- [Skills](https://github.com/tct68/claudex/blob/master/src/web/src/pages/SkillsPage.jsx): `src/web/src/pages/SkillsPage.jsx`
- [Hooks](https://github.com/tct68/claudex/blob/master/src/web/src/pages/HooksPage.jsx): `src/web/src/pages/HooksPage.jsx`
- [Agents](https://github.com/tct68/claudex/blob/master/src/web/src/pages/AgentsPage.jsx): `src/web/src/pages/AgentsPage.jsx`
- [MCP management](https://github.com/tct68/claudex/blob/master/src/web/src/pages/MCPServersPage.jsx): `src/web/src/pages/MCPServersPage.jsx`
- [Import and export](https://github.com/tct68/claudex/blob/master/src/web/src/pages/ImportExportPage.jsx): `src/web/src/pages/ImportExportPage.jsx`
- [Template preview](https://github.com/tct68/claudex/blob/master/src/web/src/components/TemplatePreviewModal.jsx): `src/web/src/components/TemplatePreviewModal.jsx`
- [Markdown preview](https://github.com/tct68/claudex/blob/master/src/web/src/components/MarkdownPreview.jsx): `src/web/src/components/MarkdownPreview.jsx`

### Server runtime

- [Workspace API](https://github.com/tct68/claudex/blob/master/src/server/routes/api.js): `src/server/routes/api.js`
- [HTTP server](https://github.com/tct68/claudex/blob/master/src/server/index.js): `src/server/index.js`
- [Workspace discovery](https://github.com/tct68/claudex/blob/master/src/server/services/workspace.js): `src/server/services/workspace.js`
- [Registry API](https://github.com/tct68/claudex/blob/master/src/server/routes/registry.js): `src/server/routes/registry.js`
- [Asset registry](https://github.com/tct68/claudex/blob/master/src/server/services/agent-registry.js): `src/server/services/agent-registry.js`

### Integrations

- [Claude CLI service](https://github.com/tct68/claudex/blob/master/src/server/services/claude.js): `src/server/services/claude.js`
- **Claude Code CLI**
- [Vision-to-UI server](https://github.com/tct68/claudex/blob/master/src/mcp-servers/vision-ui/index.js): `src/mcp-servers/vision-ui/index.js`

### Other components

- **Developer**

## Connections

- Developer → ClaudeX CLI: runs commands (evidence: `bin/cli.js`)
- ClaudeX CLI → Workspace setup: initializes workspace (evidence: `bin/cli.js`)
- ClaudeX CLI → HTTP server: starts server (evidence: `bin/cli.js`)
- Developer → Web app shell: manages workspace (evidence: `README.md`)
- Web app shell → UI layout: renders (evidence: `src/web/src/App.jsx`)
- Web app shell → Commands: routes to (evidence: `src/web/src/App.jsx`)
- Web app shell → Skills: routes to (evidence: `src/web/src/App.jsx`)
- Web app shell → Hooks: routes to (evidence: `src/web/src/App.jsx`)
- Web app shell → Agents: routes to (evidence: `src/web/src/App.jsx`)
- Web app shell → MCP management: routes to (evidence: `src/web/src/App.jsx`)
- Web app shell → Import and export: routes to (evidence: `src/web/src/App.jsx`)
- Template preview → Markdown preview: renders content (evidence: `src/web/src/components/TemplatePreviewModal.jsx`)
- HTTP server → Workspace API: mounts routes (evidence: `src/server/index.js`)
- HTTP server → Registry API: mounts routes (evidence: `src/server/index.js`)
- HTTP server → Workspace discovery: reads workspace (evidence: `src/server/index.js`)
- HTTP server → Claude CLI service: checks installation (evidence: `src/server/index.js`)
- Workspace API → Workspace discovery: gets workspace info (evidence: `src/server/routes/api.js`)
- Workspace API → Claude CLI service: tests commands (evidence: `src/server/routes/api.js`)
- Registry API → Asset registry: discovers assets (evidence: `src/server/routes/registry.js`)
- Claude CLI service → Claude Code CLI: spawns process (evidence: `src/server/services/claude.js`)
- Developer → Vision-to-UI server: uses MCP integration (evidence: `README.md`)
