graphgateway

graph-gateway

HTTP gateway component for external access to the knowledge graph via GraphQL and MCP protocols.

Overview

The graph-gateway component provides HTTP endpoints for querying and mutating the knowledge graph. It serves as the external access layer, translating HTTP requests into KV reads (via QueryManager) and NATS mutations.

Architecture

                                   ┌─────────────────────┐
HTTP /graphql ──────────────────►  │                     │
                                   │   graph-gateway     │ ──► NATS graph.mutation.*
HTTP /mcp ──────────────────────►  │                     │
                                   │   (QueryManager)    │ ──► KV reads (direct)
HTTP / (playground) ────────────►  │                     │
                                   └─────────────────────┘

Features

• GraphQL API: Full query and mutation support for graph operations
• MCP Protocol: Model Context Protocol for LLM tool integration
• GraphQL Playground: Interactive development IDE
• Read-through KV: Direct KV access for queries (no NATS overhead)
• Mutation Forwarding: Mutations sent via NATS to graph-ingest

Configuration

{
  "name": "graph-gateway",
  "type": "gateway",
  "config": {
    "graphql_path": "/graphql",
    "mcp_path": "/mcp",
    "bind_address": "localhost:8080",
    "enable_playground": true,
    "ports": {
      "inputs": [
        {"name": "http", "type": "http", "subject": "/graphql"}
      ],
      "outputs": [
        {"name": "mutations", "type": "nats-request", "subject": "graph.mutation.*"}
      ]
    }
  }
}

Configuration Options

HTTP Endpoints

GraphQL (/graphql)

Standard GraphQL endpoint supporting:

Queries:

• entity(id: ID!): Fetch single entity
• entities(filter: EntityFilter): Search entities
• triples(subject: ID, predicate: String, object: ID): Query triples
• traverse(start: ID!, depth: Int!): Graph traversal
• communities(algorithm: String): Community detection results

Mutations:

• createEntity(input: EntityInput!): Create new entity
• updateEntity(id: ID!, input: EntityInput!): Update entity
• deleteEntity(id: ID!): Delete entity
• createTriple(input: TripleInput!): Create relationship
• deleteTriple(id: ID!): Delete relationship

MCP (/mcp)

Model Context Protocol endpoint for LLM integration:

Tools:

• graph_query: Execute graph queries
• entity_lookup: Find entities by alias or ID
• relationship_find: Discover relationships
• context_build: Build context from graph neighborhood

Playground (/)

When enabled, serves an interactive GraphQL IDE for:

• Query composition and testing
• Schema exploration
• Response visualization

KV Bucket Access

The gateway reads from multiple KV buckets via QueryManager:

Integration

With graph-ingest

Mutations received by the gateway are forwarded via NATS:

• graph.mutation.entity.create
• graph.mutation.entity.update
• graph.mutation.entity.delete
• graph.mutation.triple.add
• graph.mutation.triple.delete

With QueryManager

The gateway uses QueryManager for complex read operations:

• Multi-hop traversals
• Filtered entity searches
• Aggregation queries

Security Considerations

Production deployments should:

1. Disable playground (enable_playground: false)
2. Deploy behind authentication proxy
3. Implement rate limiting
4. Use TLS termination at load balancer

Deployment

All Tiers

The gateway is required in all deployment tiers:

{
  "components": [
    {"type": "processor", "name": "graph-ingest"},
    {"type": "processor", "name": "graph-index"},
    {"type": "gateway", "name": "graph-gateway"}
  ]
}

High Availability

For production, deploy multiple gateway instances behind a load balancer. Each instance maintains its own QueryManager with KV connections.