Skip to content

PostGraphile API Server Foundation

Objective

Set up PostGraphile GraphQL API server with Express, authentication, and proper configuration for development and production.

Background

PostGraphile will auto-generate our GraphQL API from the PostgreSQL schema, providing instant CRUD operations with proper authorization.

Tasks

  • Create packages/api-server structure
  • Set up Express server with PostGraphile middleware
  • Configure JWT authentication
  • Add development vs production settings
  • Implement GraphiQL for development
  • Add CORS configuration
  • Set up health check endpoint
  • Configure watch mode for schema changes

Package Structure

packages/api-server/
├── src/
│   ├── server.js
│   ├── config.js
│   ├── middleware/
│   │   └── auth.js
│   └── plugins/
│       └── custom-plugins.js
├── package.json
├── .env.example
└── README.md

Core Configuration

// src/server.js
const postgraphile = require('postgraphile');
const express = require('express');

const app = express();

app.use(
  postgraphile(DATABASE_URL, 'app_public', {
    watchPg: true,
    graphiql: true,
    enhanceGraphiql: true,
    dynamicJson: true,
    setofFunctionsContainNulls: false,
    ignoreRBAC: false,
    showErrorStack: 'json',
    extendedErrors: ['hint', 'detail', 'errcode'],
    appendPlugins: [require('@graphile-contrib/pg-simplify-inflector')],
    exportGqlSchemaPath: 'schema.graphql',
    pgDefaultRole: 'anonymous',
    jwtSecret: process.env.JWT_SECRET,
    jwtPgTypeIdentifier: 'app_public.jwt_token',
  })
);

Acceptance Criteria

  • Server starts on port 5000
  • GraphiQL available at /graphiql
  • JWT authentication works
  • Can query database tables via GraphQL
  • Mutations respect RLS policies
  • Schema auto-updates on DB changes
  • Health check returns 200 OK

Environment Variables

DATABASE_URL=postgres://user:pass@localhost:5432/melange_mvp
JWT_SECRET=your-secret-key
NODE_ENV=development
PORT=5000

Testing

  • GraphQL introspection query works
  • Authentication flow (login/signup)
  • Authorized vs unauthorized queries
  • Schema export for client generation

Dependencies

  • Express
  • PostGraphile
  • @graphile-contrib/pg-simplify-inflector
  • postgraphile-plugin-connection-filter
  • CORS
  • dotenv

Priority: 🔴 Critical

API layer for entire application.

Estimated Effort: 2 days

Scripts

{
  "scripts": {
    "dev": "nodemon src/server.js",
    "start": "node src/server.js",
    "export-schema": "node scripts/export-schema.js"
  }
}

CI Validation

  • Server starts successfully
  • GraphQL endpoint responds
  • Schema exports without errors

Depends On

  • #37 Database Foundation (must have schema to expose)