Graph Service

The Graph service is Construct's data aggregation, querying, and platform deployment layer. It combines a GraphQL API for cross-service data access with the platform-as-a-service (PaaS) functionality for application deployment and orchestration.

Background

The Graph service incorporates what was previously a standalone PaaS service. The comprehensive documentation in infra/graph/docs/ covers both the GraphQL layer and the deployment/orchestration capabilities (vision, architecture, data models, SDK, implementation plans, database design).

Overview

The Graph service serves two primary roles:

Data Layer — Provides a unified GraphQL API that aggregates data from all infrastructure services, enabling complex queries, relationship mapping, and real-time subscriptions.

Deployment Platform — Manages application deployments, container orchestration, environment configuration, auto-scaling, and operational monitoring (inherited from the PaaS service).

Service Information

Location: infra/graph/

Technology: Go backend + Vue.js frontend

Database: PostgreSQL with graph extensions

API Port: 8006 (development)

API Format: GraphQL + RESTful HTTP endpoints

Documentation

The Graph service has comprehensive documentation in infra/graph/docs/:

Available Documentation

File	Topic
01-vision.md	Vision and goals for the platform
02-architecture.md	System architecture and design patterns
03-data-models.md	Data models and entity relationships
04-sdk.md	SDK documentation for client integration
05-implementation-plan.md	Implementation roadmap and milestones
06-database-design.md	Database schema and design decisions

These docs are the canonical reference for understanding the Graph service's internals, especially the deployment and orchestration capabilities.

GraphQL API

Schema Overview

The GraphQL schema provides types for querying and mutating data across all infrastructure services:

Core Types: User, Team, Organization, Project, Service

Deployment Types: Deployment, Environment, Container, ScalingPolicy

Operational Types: HealthCheck, Metric, Log, Event

Query Examples

# Get user with their projects and deployments
query {
  user(id: "user_123") {
    name
    email
    projects {
      name
      deployments {
        status
        environment
        version
      }
    }
  }
}

# Get deployment status with metrics
query {
  deployment(id: "deploy_456") {
    status
    containers {
      name
      state
      restarts
    }
    metrics {
      cpu
      memory
      requests
    }
  }
}

Subscriptions

Real-time subscriptions for deployment events, health changes, and metric updates:

subscription {
  deploymentStatusChanged(projectId: "proj_789") {
    deploymentId
    newStatus
    timestamp
  }
}

Deployment Capabilities

The Graph service manages application lifecycle:

• Multi-environment support: dev, staging, production
• Deployment strategies: Blue-green, canary, rolling updates
• Auto-scaling: Based on CPU, memory, and request metrics
• Health management: Automatic health checks and self-healing
• Resource optimization: Container resource allocation and limits

REST Endpoints (Deployment)

• GET /api/deployments - List deployments
• POST /api/deployments - Create deployment
• GET /api/deployments/:id - Deployment details
• PUT /api/deployments/:id - Update deployment
• POST /api/deployments/:id/restart - Restart application
• POST /api/deployments/:id/rollback/:version - Rollback to version
• GET /api/deployments/:id/logs - Deployment logs
• GET /api/deployments/:id/metrics - Performance metrics

Configuration

The Graph service is configured via environment variables or a config file:

# Environment variables
DATABASE_URL=postgresql://user:pass@localhost:5432/graph
PORT=8006
GRAPHQL_PLAYGROUND=true
LOG_LEVEL=info

Development

cd infra/graph
go mod download
go run ./cmd/graph

# GraphQL playground: http://localhost:8006/playground
# Health check: http://localhost:8006/health

Related Documentation

• Services Directory — Overview of all infrastructure services
• Infrastructure Overview — High-level architecture
• infra/graph/docs/ — Detailed internal documentation (vision, architecture, data models, SDK, implementation plan, database design)