# r488it/claude_hands architecture

> Architecture diagram of the GitHub repository r488it/claude_hands, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/r488it/claude_hands
- Repository: https://github.com/r488it/claude_hands

## Overview

##### Project Type and Purpose
- This project is an integration tool that bridges Claude Desktop (via MCP interfaces) with services for enhanced search (Tavily) and code development (via a preconfigured Docker environment). It also hints at some ChatGPT integration (see chatgpt_mcp_agent.config.yaml).
- The README emphasizes ease of deployment (using Docker and Docker Compose) and integration with external applications (Claude Desktop, Tavily API). This signals a full-fledged integration and service orchestration environment rather than a traditional monolithic app.

##### File Structure
- Top-level files include configuration files (.env, claude_desktop_config.json, chatgpt_mcp_agent.config.yaml), Dockerfiles (Dockerfile_claude_code_sse, Dockerfile_tavily), and docker-compose.yml, which points to container orchestration.
- The presence of assets and prompt/knowledge markdowns indicates a UI component or at least visual documentation support.
- The structure suggests that there are separate Docker images (likely one for “Claude Code” and another for “Tavily”) and configurations meant to integrate with external applications (Claude Desktop, Tavily API) and possibly ChatGPT Desktop.

##### Understanding Key Architectural Elements from the README
- The README outlines setup instructions that include configuring environment variables, editing volume paths in docker-compose.yml, and starting services via Docker Compose.
- Integration with Claude Desktop is achieved by copying a specific configuration file (claude_desktop_config.json) to the user’s desktop installation.
- There is also an emphasis on compatibility with multiple desktop environments (both Claude and ChatGPT Desktop).

a. Main Components:
- Docker Compose Orchestrator: Central to starting and managing services.
- Docker Containers:
- Claude Code Service (from Dockerfile_claude_code_sse): Handles core functionality possibly related to code execution and MCP communication.
- Tavily Service (from Dockerfile_tavily): Enables enhanced information retrieval via Tavily.
- (Optionally) ChatGPT MCP Agent: Indicated by chatgpt_mcp_agent.config.yaml, suggesting additional service integration.
- Configuration Files:
- .env: Contains environmental variables (e.g., Tavily API key).
- claude_desktop_config.json: For configuring Claude Desktop.
- External Services:
- Claude Desktop Application: The user’s desktop application that communicates with the Docker services.
- Tavily API: External search service integrated via API calls.
- Possibly ChatGPT Desktop (if activated via configuration).

b. Relationships and Interactions:
- Docker Compose acts as the central control plane that instantiates and links the various containerized services.
- The Claude Code Service and Tavily Service are containerized and might communicate either directly via internal networking (as established by docker-compose) or indirectly through shared volumes and network ports.
- External client applications (Claude Desktop and potentially ChatGPT Desktop) interface with these services via the MCP protocol, using the configurations placed in claude_desktop_config.json and chatgpt_mcp_agent.config.yaml.
- The system uses environmental variables (from .env) to securely store sensitive information such as the Tavily API key. This file influences how containers authenticate with the external Tavily API.

c. Architectural Patterns and Design Principles:
- Containerization for isolation and reproducibility: each major service is encapsulated in its own Docker container.
- Separation of concerns: distinct Docker containers (one for Claude code functionality and another for Tavily search) ensure modularity.
- External integration via configuration: adherence to external protocol interfaces (MCP) to interact with desktop applications.
- Volume binding in docker-compose.yml ensures that the workspace persists between container restarts.

d. Technologies and Frameworks:
- Docker and Docker Compose for environment orchestration.
- Claude Desktop and ChatGPT Desktop (for MCP interfaces).
- External APIs like Tavily.
- JSON and YAML configuration formats ensuring flexible integration.

##### Specific Elements
- Clear labels for each component:
- “Docker Compose Orchestrator”
- “Claude Code Container” (from Dockerfile_claude_code_sse)
- “Tavily Service Container” (from Dockerfile_tavily)
- “ChatGPT MCP Agent Container” (if relevant)
- “.env Configuration” as a configuration data source.
- Startup and management by Docker Compose.
- Communication flows from Docker containers to external services (Claude Desktop, Tavily API).
- Data flows that may involve shared volumes (e.g., workspace directory mapping).
- Rectangles for containerized services.
- Incorporate annotations such as protocol names (“MCP”, “API Call”, “Volume Mapping”).

##### Overall Advice
- Be as detailed as possible—don’t hesitate to break down each Docker service into its subcomponents if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Block
    subgraph "Configuration"
        ENV[".env Configuration"]:::config
        CDE["Claude Desktop Configuration File"]:::config
    end

    %% Orchestration Layer
    DCOrchestrator["Docker Compose Orchestrator"]:::orchestrator

    %% Containerized Services
    subgraph "Container Services"
        Code["Claude Code Container"]:::container
        Tavily["Tavily Service Container"]:::container
        ChatGPT["ChatGPT MCP Agent Container"]:::container
    end

    %% External Systems
    subgraph "External Integrations"
        ClaudeDesktop["Claude Desktop Application"]:::external
        TavilyAPI["Tavily API"]:::external
        ChatGPTDesktop["ChatGPT Desktop Application"]:::external
    end

    %% Relationships
    ENV --> DCOrchestrator
    DCOrchestrator --> Code
    DCOrchestrator --> Tavily
    DCOrchestrator --> ChatGPT

    CDE --> ClaudeDesktop

    Code -->|"MCP"| ClaudeDesktop
    Tavily -->|"API"| TavilyAPI
    ChatGPT -->|"MCP"| ChatGPTDesktop

    %% Click Events
    click DCOrchestrator "https://github.com/r488it/claude_hands/blob/main/docker-compose.yml"
    click Code "https://github.com/r488it/claude_hands/tree/main/Dockerfile_claude_code_sse"
    click Tavily "https://github.com/r488it/claude_hands/tree/main/Dockerfile_tavily"
    click ChatGPT "https://github.com/r488it/claude_hands/blob/main/chatgpt_mcp_agent.config.yaml"
    click ENV "https://github.com/r488it/claude_hands/blob/main/.env"
    click CDE "https://github.com/r488it/claude_hands/blob/main/claude_desktop_config.json"

    %% Styling
    classDef config fill:#e6f2ff,stroke:#0066cc,stroke-width:2px;
    classDef orchestrator fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef container fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef external fill:#d9ead3,stroke:#38761d,stroke-width:2px;
```
