edge-graphql

GraphQL gateway generated from an OpenAPI contract using GraphQL Mesh Compose and served by Hive Gateway.

This repository is focused on a simple, explicit flow:

1. swagger-spec.json is the source of truth for REST operations.
2. mesh.config.ts composes that contract into supergraph.graphql.
3. gateway.config.ts serves the supergraph and applies runtime concerns (headers, endpoints, OpenTelemetry).

---

Architecture at a glance

Client -> /graphql (Hive Gateway)
       -> supergraph.graphql (generated by mesh-compose)
       -> EdgeAPI subgraph (REST transport)
       -> EDGE upstream base URL

---

Repository walkthrough

Path	Purpose
swagger-spec.json	OpenAPI contract (source of truth)
mesh.config.ts	Mesh Compose config using @omnigraph/openapi
supergraph.graphql	Generated federation artifact (do not hand-edit)
gateway.config.ts	Hive Gateway runtime config (headers, endpoints, OTel)
docs/project-capabilities.md	Current capability map and where to make changes
tests/openapi.spec.js	Guardrails for OpenAPI/gateway wiring
.github/workflows/	CI, deployment, and spec-sync automation
.github/skills/	Local reusable skills for doc-driven agent workflows
AGENT.md	Agent-agnostic operating guide for contributors/assistants

---

Requirements

• Node.js 24.15.0 (from .nvmrc)
• npm

---

Setup

1. Copy environment template:
   • cp .env.example .env
2. Set at least:
   • EDGE (upstream REST base URL)
3. Install dependencies:
   • npm ci
4. Build supergraph:
   • npm run build
5. Start gateway:
   • npm run dev

---

Scripts

• npm run dev — compose supergraph.graphql and start Hive Gateway
• npm run start — same as dev (production runtime entry)
• npm run build — compose supergraph only
• npm run lint — ESLint
• npm run typecheck — TypeScript checks
• npm test — Node test runner (tests/**/*.js)

---

OpenAPI → Mesh → Supergraph workflow

When changing API surface area:

1. Edit swagger-spec.json.
2. Recompose: npm run build.
3. Inspect supergraph.graphql diff.
4. Validate runtime configuration in gateway.config.ts (headers, endpoints, tracing).
5. Run verification:
   • npm run lint
   • npm run typecheck
   • npm test

supergraph.graphql is generated output. Always modify source files, then regenerate.

---

Current GraphQL surface (from OpenAPI)

Current REST paths and their generated Query fields:

REST path	Method	GraphQL Query field
/v1/config	GET	config
/v1/news/feed	GET	newsFeed
/v1/news	GET	news
/v1/episodes	GET	episodes
/v1/series	GET	series
/v1/studios	GET	studio
/v1/people	GET	person
/v1/characters	GET	character
/v1	GET	index

---

Runtime configuration

Mesh composition (mesh.config.ts)

• Uses loadOpenAPISubgraph('EdgeAPI', ...)
• Reads EDGE from env
• Loads swagger-spec.json

Gateway runtime (gateway.config.ts)

• Serves ./supergraph.graphql
• Custom transport header forwarding for EdgeAPI
• Health/readiness endpoints
• GraphiQL toggle via env
• OpenTelemetry bootstrap + graceful shutdown

---

OpenTelemetry (current + improvement direction)

Detailed plan: docs/otel-enrichment-plan.md

Current state:

• Node SDK initialized when OTLP endpoint(s) are present
• Supports traces, metrics, and logs over OTLP HTTP
• openTelemetry.traces enabled in Hive Gateway
• Graceful shutdown flushes SDK on SIGINT/SIGTERM
• Telemetry bootstrap is centralized in telemetry.ts with env-driven signal toggles and batch controls

Phase 1 tuning knobs (examples):

• OTEL_TRACES_ENABLED, OTEL_METRICS_ENABLED, OTEL_LOGS_ENABLED
• OTEL_SERVICE_NAME (service version auto-resolves from package.json; override with OTEL_SERVICE_VERSION only when needed)
• OTEL_METRIC_EXPORT_INTERVAL, OTEL_METRIC_EXPORT_TIMEOUT
• OTEL_BSP_MAX_QUEUE_SIZE, OTEL_BSP_MAX_EXPORT_BATCH_SIZE, OTEL_BSP_SCHEDULE_DELAY, OTEL_BSP_EXPORT_TIMEOUT

Recommended enrichment plan:

1. Trace quality controls
   • Add configurable sampling strategy (ratio/env-based)
   • Tune batching/export intervals for your collector latency profile
2. Span signal quality
   • Add targeted custom spans around upstream fetch behavior and auth/header propagation decisions
   • Add selective span filters to reduce noise from low-value operations
3. Correlation + diagnostics
   • Enforce request ID/log correlation and include selected context attributes
   • Enable OTEL diagnostics (OTEL_LOG_LEVEL) only for debug windows
4. Operational baselines
   • Define latency/error SLO dashboards and alert thresholds tied to generated spans

---

Docker

Build image:

• docker build -t edge-graphql:local .

Run container:

• docker run --rm -p 8800:8800 --env EDGE=http://host.docker.internal:9800 edge-graphql:local

---

CI/CD summary

• ci.yml: lint, typecheck, tests, build matrix
• quality.yml: dependency audit/outdated checks
• api-spec-gen.yml: syncs swagger-spec.json from release artifacts via PR
• deploy.yml: builds/pushes multi-arch GHCR image

---

Endpoint

• GraphQL: POST /graphql
• Health: /health
• Readiness: /ready