docs/architecture/components.md

metadata

title: System Components
description: Detailed breakdown of KGraph-MCP system components and their responsibilities

System Components

Detailed breakdown of KGraph-MCP's system components, their responsibilities, and how they interact to create an intelligent MCP orchestration platform.

🏗️ Component Architecture

KGraph-MCP is built with a layered architecture where each component has specific responsibilities:

graph TB
    subgraph "Presentation Layer"
        UI[Gradio Web UI]
        API[FastAPI REST API]
        WS[WebSocket Interface]
    end
    
    subgraph "Agent Layer"
        PA[Planner Agent]
        SA[Selector Agent]
        EA[Executor Agent]
        SV[Supervisor Agent]
    end
    
    subgraph "Knowledge Layer"
        KG[Knowledge Graph]
        ES[Embedding Service]
        RE[Reasoning Engine]
        QE[Query Engine]
    end
    
    subgraph "Integration Layer"
        MC[MCP Connectors]
        TR[Tool Registry]
        TM[Tool Manager]
    end
    
    subgraph "Data Layer"
        VDB[Vector Database]
        GDB[Graph Database]
        FS[File Storage]
    end
    
    UI --> API
    API --> PA
    PA --> SA
    SA --> EA
    EA --> SV
    
    PA --> KG
    SA --> ES
    EA --> TR
    SV --> RE
    
    KG --> GDB
    ES --> VDB
    TR --> MC
    QE --> KG

🔧 Core Components

1. Presentation Layer

Gradio Web UI

• Purpose: Interactive web interface for user interactions
• Responsibilities:
  • Collect user input and requirements
  • Display tool selection and execution results
  • Provide real-time feedback and status updates
  • Handle dynamic form generation based on tool requirements

FastAPI REST API

• Purpose: RESTful API for programmatic access
• Responsibilities:
  • Expose HTTP endpoints for all system functionality
  • Handle authentication and authorization
  • Provide OpenAPI documentation
  • Support webhook integrations

WebSocket Interface

• Purpose: Real-time bidirectional communication
• Responsibilities:
  • Stream execution progress updates
  • Handle real-time notifications
  • Support live collaboration features

2. Agent Layer

Planner Agent

• Purpose: High-level task planning and decomposition
• Responsibilities:
  • Analyze user requirements and goals
  • Break down complex tasks into manageable steps
  • Create execution plans with dependencies
  • Optimize task sequences for efficiency

Selector Agent

• Purpose: Intelligent tool selection and routing
• Responsibilities:
  • Query knowledge graph for available tools
  • Match requirements to tool capabilities
  • Rank tools based on suitability scores
  • Handle tool substitution and fallbacks

Executor Agent

• Purpose: Tool execution and orchestration
• Responsibilities:
  • Execute selected tools with proper parameters
  • Handle tool invocation protocols
  • Manage execution contexts and state
  • Coordinate multi-tool workflows

Supervisor Agent

• Purpose: Quality assurance and monitoring
• Responsibilities:
  • Monitor execution progress and health
  • Validate results and detect anomalies
  • Handle error recovery and retries
  • Ensure safety and compliance constraints

3. Knowledge Layer

Knowledge Graph

• Purpose: Semantic representation of MCP ecosystem
• Responsibilities:
  • Store tool metadata and relationships
  • Represent capabilities and requirements
  • Maintain ontology and schema definitions
  • Support complex semantic queries

Embedding Service

• Purpose: Semantic similarity and search capabilities
• Responsibilities:
  • Generate embeddings for tools and descriptions
  • Perform semantic similarity matching
  • Enable fuzzy search and discovery
  • Support multi-modal embedding types

Reasoning Engine

• Purpose: Logical inference and decision making
• Responsibilities:
  • Perform logical reasoning over knowledge graph
  • Infer implicit relationships and capabilities
  • Support rule-based decision making
  • Handle uncertainty and confidence scoring

Query Engine

• Purpose: Efficient graph querying and traversal
• Responsibilities:
  • Execute SPARQL and Cypher queries
  • Optimize query performance
  • Handle complex graph traversals
  • Support both synchronous and streaming queries

4. Integration Layer

MCP Connectors

• Purpose: Protocol adapters for MCP servers
• Responsibilities:
  • Implement MCP protocol communication
  • Handle protocol version compatibility
  • Manage connection lifecycle and health
  • Support various transport mechanisms

Tool Registry

• Purpose: Central catalog of available tools
• Responsibilities:
  • Discover and register MCP tools
  • Maintain tool metadata and documentation
  • Handle tool versioning and updates
  • Support plugin and extension mechanisms

Tool Manager

• Purpose: Tool lifecycle and resource management
• Responsibilities:
  • Manage tool instantiation and cleanup
  • Handle resource allocation and limits
  • Coordinate concurrent tool usage
  • Monitor tool performance and health

5. Data Layer

Vector Database

• Purpose: High-performance similarity search
• Responsibilities:
  • Store and index vector embeddings
  • Perform fast similarity searches
  • Support various distance metrics
  • Handle large-scale vector operations

Graph Database

• Purpose: Native graph storage and querying
• Responsibilities:
  • Store knowledge graph structure
  • Support complex graph queries
  • Maintain ACID properties
  • Handle graph updates and mutations

File Storage

• Purpose: Persistent storage for artifacts
• Responsibilities:
  • Store configuration files and schemas
  • Handle large binary assets
  • Support versioning and backup
  • Provide secure access controls

🔄 Component Interactions

Request Flow

1. User Input → Gradio UI or FastAPI
2. Planning → Planner Agent analyzes requirements
3. Tool Selection → Selector Agent queries knowledge graph
4. Execution → Executor Agent invokes selected tools
5. Monitoring → Supervisor Agent validates results
6. Response → Results returned to user interface

Data Flow

1. Knowledge Ingestion → Tools registered in knowledge graph
2. Embedding Generation → Semantic vectors created and indexed
3. Query Processing → Graph queries retrieve relevant tools
4. Execution Context → Tool parameters and state managed
5. Result Processing → Outputs validated and formatted

📊 Component Metrics

Performance Characteristics

• Planner Agent: ~100ms average planning time
• Selector Agent: ~50ms tool selection latency
• Executor Agent: Variable based on tool complexity
• Knowledge Graph: Sub-second query response times
• Embedding Service: ~10ms similarity search

Scalability Factors

• Horizontal Scaling: Agent layer and API layer
• Vertical Scaling: Database and storage layers
• Load Balancing: Request distribution across instances
• Caching: Multi-level caching for performance

🔗 Related Documentation

• Architecture Overview - High-level system architecture
• Knowledge Graph Design - Graph schema and operations
• Agent Framework - Agent coordination and communication
• API Reference - Component APIs and interfaces