backend

notifyhub

GraphQL notification service with live subscriptions over WebSocket.

GitHub repo (opens in a new tab) ↗

~/problem

A single schema, auth model and transport pair for real-time notifications, instead of a REST API with a WebSocket added on the side.

A Node.js and Express service whose whole API is GraphQL: CRUD through queries and mutations, real-time delivery through graphql-ws subscriptions. Users create channels, subscribe, and publish notifications that reach live subscribers; an APNs channel delivers to registered iOS devices.

~/highlights

  • Apollo Server 5 with graphql-ws; the WebSocket server uses noServer plus a manual upgrade handler to avoid a double-close crash on shutdown (ADR-004).
  • Prisma 7 on PostgreSQL with a generated client and pinned matching CLI, client and adapter versions.
  • JWT and bcrypt auth shared across HTTP and WebSocket, with rate limits on both paths.
  • ApnsPushChannel implemented against the PushChannel interface, tested with a real local HTTP/2 server and throwaway EC keys.
  • CI runs CodeQL, dependency review and a Docker job that boots the runtime image, applies migrations and checks health, a query and SIGTERM exit.
  • Integration tests use a real Postgres and a real WebSocket client, run in-band.

~/architecture

Architecture of notifyhubGraphQL endpoint connects to Services. Subscription server connects to PubSub. Services connects to PostgreSQL, PubSub, Push dispatcher. PubSub connects to Subscription server. Push dispatcher connects to APNs. PostgreSQL has no outgoing connections. APNs has no outgoing connections.GraphQL endpointSubscription serverServicesPubSubPush dispatcherPostgreSQLAPNs
GraphQL endpoint → Services
Queries and mutations over HTTP with rate limiting.
Subscription server → PubSub
graphql-ws over WebSocket with connection cap and upgrade limiter.
Services → PostgreSQL, PubSub, Push dispatcher
Users, channels, notifications, device tokens, push dispatch.
PubSub → Subscription server
In-process fan-out of published notifications.
Push dispatcher → APNs
WebSocket channel plus APNs channel behind one interface.
PostgreSQL
Users, channels, notifications, device tokens via Prisma.
APNs
Apple push service, reached over HTTP/2 with a signed JWT.

~/stack

  • Node.js
  • TypeScript
  • Express 5
  • Apollo Server 5
  • graphql-ws
  • Prisma 7
  • PostgreSQL
  • Docker
  • Jest

~/status

Complete and documented in project memory. Real APNs credentials are deliberately never present, so the APNs path is tested but not delivered to a device. MIT.

  • notifyhub-ios Native SwiftUI client for notifyhub with APNs push and live subscriptions.