GraphQL Federation E-Commerce Platform

A production-grade GraphQL Federation 2 e-commerce platform demonstrating hybrid protocol architecture (GraphQL + REST + gRPC) across three backend languages, fronted by Kong API Gateway and Apollo Router, with a Next.js 15 storefront and full observability.

Architecture

flowchart TB
    Browser["Browser :3000"] -->|HTTP| Kong

    subgraph Kong["Kong API Gateway :8000"]
        direction LR
        K1["Auth . Rate Limiting . CORS"]
    end

    Kong -->|"/graphql"| Router
    Kong -->|"/auth/*"| User

    subgraph Router["Apollo Router :4000"]
        direction LR
        R1["Federation 2.9 . Header Propagation . OTLP"]
    end

    Router --> Product["Product Catalog\nJava :4001"]
    Router --> Order["Order Service\nGo :4002"]
    Router --> User["User/Auth + Reviews\nTypeScript :4003"]
    Router --> Inventory["Inventory\nJava :4004"]

    Product <-->|"gRPC\n:50051"| Inventory
    Order -->|"REST\nHTTPS"| Stripe["Stripe API"]

    subgraph Observability
        OTel["OTel Collector"]
        Tempo["Grafana Tempo"]
        Prometheus
        Loki
        Alloy["Grafana Alloy"]
        Pyroscope
        Grafana
    end

    Product & Order & User & Inventory -->|OTLP| OTel
    OTel --> Tempo & Prometheus
    Alloy -->|logs| Loki
    Product & Order & User & Inventory -.->|profiles| Pyroscope
    Grafana --> Tempo & Prometheus & Loki & Pyroscope

Loading

Protocol Boundaries

Connection	Protocol
Client -> Kong	HTTP
Kong -> Apollo Router	HTTP (internal)
Router -> Subgraphs	HTTP (GraphQL over POST)
Product Catalog <-> Inventory	gRPC (protobuf over HTTP/2)
Order Service -> Stripe	HTTPS REST
All services -> OTel Collector	OTLP gRPC

Technology Stack

Component	Technology	Version
Federation Router	Apollo Router	2.1.1
Federation Spec	Apollo Federation	2.9
API Gateway	Kong OSS	3.9
Java Framework	Micronaut	4.7.6
Java	OpenJDK	21 LTS
Go	Go	1.23
Go GraphQL	gqlgen	0.17.63
TypeScript	TypeScript	5.7
Apollo Server	@apollo/server	4.11
Frontend	Next.js	15.1
CSS	TailwindCSS	4.0
Search	Meilisearch	1.12
Object Storage	MinIO	latest
Database	PostgreSQL	17
Cache	Redis	7.4
Tracing	Grafana Tempo	2.7
Metrics	Prometheus	3.2
Dashboards	Grafana	11.5
Logs	Loki	3.4
Log Collector	Grafana Alloy	1.5
Profiling	Grafana Pyroscope	1.10
Telemetry	OTel Collector	0.115.1

Quick Start

# Clone and configure
git clone https://github.com/techishthoughts-org/graphql-federation.git
cd graphql-federation
cp .env.example .env   # Edit with your values

# Start infrastructure + all services
make up

# Include observability stack (Tempo, Grafana, Prometheus, Loki, Pyroscope)
make up-full

# Verify all services are healthy
make health

Services

Service	Language	Port	Entities
Product Catalog	Java 21 / Micronaut	4001	Product, Category
Inventory	Java 21 / Micronaut	4004, gRPC 50051	Inventory (extends Product)
Order Service	Go 1.23 / gqlgen	4002	Order, OrderItem (refs User, Product)
User/Auth + Reviews	TypeScript / Apollo Server	4003	User, Review (extends Product)
Frontend	Next.js 15 / React 19	3000	—

Federation Schema

Entity ownership and cross-service references:

• Product @key(fields: "id") — owned by Product Catalog, extended by Inventory (adds inventory), User Service (adds reviews, averageRating), Order Service (referenced in OrderItem)
• User @key(fields: "id") — owned by User/Auth, extended by Order Service (adds orders)
• Order @key(fields: "id") — owned by Order Service
• Review @key(fields: "id") — owned by User/Auth
• Category @key(fields: "id") — owned by Product Catalog

Key Commands

make up                    # Start infrastructure + services
make up-full               # Include observability stack
make down                  # Stop all containers
make build                 # Build all Docker images
make compose-supergraph    # Recompose federated schema with Rover
make logs SVC=user         # Tail logs for a service
make health                # Check all service health endpoints
make seed                  # Load demo data
make clean                 # Remove all volumes and containers
make validate              # Deep local validation across services + docs
make validate-observability # Validate observability config wiring

Development

Each service can run independently outside Docker for faster iteration. See the Development Guide for per-service setup instructions.

# Start just infrastructure
docker compose up -d postgres redis meilisearch minio minio-init mailpit

# Run services locally (separate terminals)
cd services/user-ts && npm install && npm run dev
cd services/product-catalog-java && gradle run
cd services/inventory-java && gradle run
cd services/order-go && go run cmd/server/main.go
cd frontend && npm run dev

Observability

Tool	Port	Purpose
Grafana	localhost:3001	Dashboards (traces, metrics, logs, profiles)
Tempo	localhost:3200	Distributed tracing (TraceQL)
Prometheus	localhost:9090	Metrics storage and queries
Pyroscope	localhost:4040	Continuous profiling
Mailpit	localhost:8025	Email testing
MinIO Console	localhost:9001	Object storage management
Meilisearch	localhost:7700	Search engine dashboard
Apollo Sandbox	localhost:4000	GraphQL IDE (when Router sandbox is enabled)

Documentation

Document	Description
Full README	Complete project overview, technology stack, and setup
Architecture	System architecture, request flows, protocols, and deployment
API Reference	GraphQL queries/mutations, REST endpoints, gRPC services
Development Guide	Local setup, per-service workflows, debugging, and CI
Improvement Roadmap	Deep investigation findings and prioritized improvement plan
Validation Report	Integrated validation outcomes for the latest audit

Project Structure

graphql_federation/
├── gateway/
│   ├── kong/kong.yml                    # Kong declarative config
│   └── router/
│       ├── router.yaml                  # Apollo Router config
│       ├── supergraph.graphql           # Composed schema (generated)
│       └── supergraph-config.yaml       # Rover composition input
├── services/
│   ├── product-catalog-java/            # Micronaut + GraphQL + gRPC client
│   ├── inventory-java/                  # Micronaut + GraphQL + gRPC server
│   ├── order-go/                        # Go + gqlgen + Stripe REST
│   └── user-ts/                         # Apollo Server + Drizzle ORM
├── frontend/                            # Next.js 15 + Apollo Client + Tailwind
├── proto/inventory/v1/inventory.proto   # Shared protobuf definitions
├── infra/docker/                        # DB init scripts, MinIO setup
├── observability/                       # OTel Collector, Tempo, Prometheus, Grafana, Loki, Alloy, Pyroscope
├── docker-compose.yml                   # Core services
└── docker-compose.observability.yml     # Observability overlay

License

This project is for educational and demonstration purposes.