Skip to content

Latest commit

 

History

History
100 lines (74 loc) · 3.14 KB

README.md

File metadata and controls

100 lines (74 loc) · 3.14 KB

Backend Service

This repository contains a GraphQL API service built with PostGraphile, providing a thin API layer on top of PostgreSQL. The service handles authentication via JWT tokens (compatible with Supabase) and provides dynamic schema generation during development.

Architecture

The backend is built using:

  • PostGraphile: Auto-generates a GraphQL API from your PostgreSQL schema
  • Express: Web framework for handling HTTP requests
  • JWT: Token-based authentication compatible with Supabase
  • Docker: Containerization for consistent deployment

Development Setup

Prerequisites

  • Node.js (v18+)
  • PostgreSQL database
  • Docker (for deployment)

Environment Variables

DATABASE_URL=postgresql://user:password@host:5432/dbname
JWT_SECRET=your_jwt_secret
PORT=5001 (default)
CORS_ORIGIN=* (default)

Getting Started

  1. Install dependencies:
npm install
  1. Start in development mode:
npm run start:watch

This will run the server in watch mode, which:

  • Automatically restarts on file changes
  • Regenerates the GraphQL schema (schemas/schema.graphql)
  • Enables GraphiQL interface for API exploration
  • Provides detailed error messages and debugging information

Authentication

The service uses JWT tokens for authentication, compatible with Supabase's auth system. The JWT middleware:

  • Extracts the JWT token from the Authorization header
  • Verifies the token signature using JWT_SECRET
  • Sets PostgreSQL role and user context based on token claims
  • Provides role-based access control through PostgreSQL policies

API Features

  • GraphiQL Interface: Available at /api/v1/graphiql for API exploration
  • Dynamic JSON: Native JSON type handling
  • Query Batching: Optimized multiple query execution
  • Subscriptions: Real-time data updates (enabled but requires additional setup)
  • Simplified Schema: Uses @graphile-contrib/pg-simplify-inflector for cleaner naming

Deployment

The service is deployed using GitHub Actions and Docker. The workflow:

  1. Builds Docker image
  2. Transfers image to deployment server
  3. Runs container with proper configuration

Required Secrets

Configure these secrets in GitHub repository settings:

  • SSH_PRIVATE_KEY: SSH key for server access
  • SERVER_HOST: Deployment server hostname
  • SERVER_USER: SSH user for deployment
  • DATABASE_URL: PostgreSQL connection string
  • JWT_SECRET: Secret for JWT verification

Docker Configuration

The container runs with:

  • Port 5001 exposed
  • Automatic restart policy
  • Health checks every 30s
  • Log rotation (10MB max, 3 files)
  • Memory limits and resource constraints

Available Scripts

  • npm start: Run in development mode
  • npm run start:watch: Run with auto-reload
  • npm run ts: Run TypeScript type checking in watch mode
  • npm run ts:check: One-time TypeScript check
  • npm run format: Format code using Prettier
  • npm run format:check: Check code formatting

API Documentation

The GraphQL schema is available through the GraphiQL interface at /api/v1/graphiql. In development mode, the schema is also exported to schemas/schema.graphql for version control and frontend consumption.