How interledger/rafiki works
Project Type and Purpose
• Rafiki is a full-stack, microservices-style platform for regulated “account servicing entities” to expose Interledger functionality.
• Main goals:
• Expose Admin APIs (GraphQL) for configuration (peers, assets, tenants, wallet-addresses)
• Expose Open Payments API (GraphQL & REST) for third-party payment initiation and data access
• Expose SPSP endpoints for simple payments
• Host a reference GNAP authorization server for Open Payments token issuance
• Use TigerBeetle for high-throughput accounting and Postgres for auth and metadata
• Provide a React/Remix admin UI and comprehensive docs
High-Level Component Analysis
• packages/auth → GNAP authorization server (Node, Express, GraphQL, Postgres via Knex)
• packages/backend → Core business-logic service (TypeScript, GraphQL resolvers, REST routes, ILP connector plugin)
• packages/frontend → React/Remix admin UI (UI components, Apollo client, Kratos identity integration)
• infra/helm/rafiki → Kubernetes charts bundling rafiki-auth, rafiki-backend, rafiki-frontend + dependencies (postgresql, redis, tigerbeetle)
• infra/helm/tigerbeetle → Dedicated chart for the TigerBeetle ledger cluster
• localenv/telemetry → OpenTelemetry collector, Prometheus, Grafana
Interactions and Data Flow
• Client (browser or third-party) → Frontend UI / Direct API calls
• Frontend UI → GraphQL queries/mutations to rafiki-backend (via Apollo) → backend services
• rafiki-backend:
• Validates access credentials (via token introspection to rafiki-auth)
• Routes Open Payments GraphQL & REST requests to open_payments modules
• Routes SPSP HTTP requests to ILP connector handlers
• Uses TigerBeetle (gRPC or HTTP) for ledger operations and Postgres/Redis for metadata & caching
• rafiki-auth:
• Handles GNAP grant flows: issue, validate, revoke access tokens
• Stores grant and token state in Postgres
• TigerBeetle cluster:
• Manages account and transfer records at very high throughput
• Redis:
• Caching, locking, rate-limiting
• Postgres:
• Auth metadata (grants, tokens, tenants)
• System configuration (assets, peers, webhooks)
• Telemetry:
• rafiki-backend and rafiki-auth push traces/metrics to OpenTel collector → Prometheus/Grafana
Architectural Patterns & Design Principles
• Microservices: individual containers for auth, backend, frontend
• Hexagonal/clean architecture: each package’s src/… directory isolates domain logic, transport adapters (HTTP, GraphQL, ILP, telemetry)
• API Gateway style: rafiki-backend is a unified entrypoint for both GraphQL and REST endpoints
• Data-store segregation: TigerBeetle for OLTP ledger, Postgres for relational config, Redis for ephemeral state
• CI/CD: .github/actions for building images, pushing manifests, running CodeQL