GraphQL Proxy Server

A high-performance GraphQL proxy server built with Elysia.js (Bun runtime) that sits between GraphQL clients and upstream GraphQL APIs. Provides caching, offline mutation queuing, and local data synchronization.

🚀 Features

• Three Operational Modes:

  • GETMODE: Read-only proxy with response caching
  • SETMODE: Offline-capable with mutation queuing and local sync
  • CRUDMODE: Strict online bidirectional synchronization

• Performance Optimized:

  • File-based response caching
  • Automatic cache key generation
  • Efficient JSON storage

• Offline Support:

  • Mutation queuing for offline operations
  • Local database synchronization
  • Automatic queue processing on reconnection

• Production Ready:

  • Docker containerization
  • CORS configuration
  • Health monitoring endpoints
  • Comprehensive error handling

📋 Prerequisites

• Node.js 18+ or Bun runtime
• WordPress with WPGraphQL plugin installed
• Upstream GraphQL API endpoint

🛠️ Installation

Using Bun (Recommended)

# Clone the repository
git clone https://github.com/buildy-ui/endpoint.git
cd graphql-proxy

# Install dependencies
bun install

# Copy environment configuration
cp env.example .env

# Edit .env with your settings
nano .env

Using npm

# Clone the repository
git clone https://github.com/buildy-ui/endpoint.git
cd graphql-proxy

# Install dependencies
npm install

# Copy environment configuration
cp env.example .env

# Edit .env with your settings
nano .env

⚙️ Configuration

Edit the .env file with your GraphQL endpoint and settings:

# Required: Your GraphQL endpoint
UPSTREAM_GRAPHQL_ENDPOINT=https://your-site.com/graphql

# Optional: Authentication token for mutations
AUTH_TOKEN=your-jwt-token-here

# Optional: Server port (default: 5001)
PORT=5001

# Optional: GraphQL mode (default: GETMODE)
GRAPHQL_MODE=SETMODE

Configuration Options

Variable	Description	Default
UPSTREAM_GRAPHQL_ENDPOINT	GraphQL API URL	Required
AUTH_TOKEN	JWT token for authenticated requests	Optional
GRAPHQL_MODE	GETMODE/SETMODE/CRUDMODE	GETMODE
PORT	Server listening port	5001
CACHE_DIR	Cache storage directory	./data/graphql-cache
QUEUE_DIR	Mutation queue directory	./data/mutation-queue
LOCAL_DB_PATH	Local database file	./data/local-db.json
PATHS_RELATIVE_TO	Base for relative paths: cwd or script	cwd
PATHS_BASE_DIR	Explicit base directory for relative paths	(unset)
CORS_ORIGIN	CORS allowed origins	*

🚀 Quick Start

1. Start the Server

# Using Bun
bun run start

# Using npm
npm run start

# Development mode
bun run dev

2. Test the Installation

# Check server health
curl http://localhost:5001/health

# Test GraphQL query
curl -X POST http://localhost:5001/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ posts(first: 1) { nodes { id title } } }"}'

3. Test Caching

Run the same query twice to see caching in action:

# First request (cache miss)
curl -X POST http://localhost:5001/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ posts(first: 1) { nodes { id title } } }"}' \
  -v

# Second request (cache hit - check x-cache header)
curl -X POST http://localhost:5001/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ posts(first: 1) { nodes { id title } } }"}' \
  -v

📚 Documentation

Complete documentation is available in the docs/ directory:

📖 Getting Started

• Quick Setup Guide
• Environment Variables

🔧 API Reference

• Server API Reference

🚀 Deployment

• Docker Deployment

📚 Integration Guides

• CMS Integration (101 Level) - Full CRUD operations
• GETMODE App Integration (101 Level) - Read-only applications
• WordPress GraphQL Setup (101 Level) - Backend configuration

🐛 Troubleshooting

• Common Issues

🏗️ Operational Modes

GETMODE (Read-Only)

• Queries: Forward to upstream with caching
• Mutations: Blocked with error
• Use Case: Public blogs, documentation sites

SETMODE (Offline-Capable)

• Queries: Forward to upstream with caching
• Mutations: Execute online, queue offline, sync to local DB
• Use Case: CMS applications, mobile apps

CRUDMODE (Strict Online)

• Queries: Forward to upstream with caching
• Mutations: Execute online only, fail if offline
• Use Case: Real-time collaborative editing

🐳 Docker Deployment

Build and Run

# Build image
docker build -t graphql-proxy .

# Run container
docker run -d \
  --name graphql-proxy \
  -p 5001:5001 \
  -e UPSTREAM_GRAPHQL_ENDPOINT=https://your-site.com/graphql \
  -e GRAPHQL_MODE=SETMODE \
  -v ./data:/app/data \
  graphql-proxy

Docker Compose

version: '3.8'
services:
  graphql-proxy:
    image: graphql-proxy:latest
    ports:
      - "5001:5001"
    environment:
      - UPSTREAM_GRAPHQL_ENDPOINT=https://your-site.com/graphql
      - GRAPHQL_MODE=SETMODE
    volumes:
      - ./data:/app/data
    restart: unless-stopped

🔧 Development

Available Scripts

# Development server with hot reload
bun run dev

# Production server
bun run start

# Build (if needed)
bun run build

Project Structure

├── server/
│   └── index.ts          # Main server implementation
├── docs/                 # Documentation
├── data/                 # Runtime data storage
├── env.example           # Environment configuration template
├── package.json          # Dependencies and scripts
└── AGENTS.md            # AI agent instructions

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript strict mode
• Add comprehensive error handling
• Update documentation for new features
• Test with all three operational modes
• Ensure CORS and security considerations

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Current Status

This is the first raw version of the GraphQL proxy server. It is currently focused on the WordPress entity structure (posts, categories, tags, pages, authors) and provides basic CRUD operations through the three operational modes.

Future enhancements will include:

• More flexible entity schemas beyond WordPress
• Plugin system for custom data transformers
• Advanced caching strategies
• Webhook support for real-time updates
• Additional storage adapters
• Enhanced monitoring and metrics

---

Built with ❤️ using Elysia.js and Bun