# interledger/rafiki architecture

> Architecture diagram of the GitHub repository interledger/rafiki, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/interledger/rafiki
- Repository: https://github.com/interledger/rafiki

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        Browser["Browser (Admin UI)"]:::external
        ThirdParty["Third-Party Systems"]:::external
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Frontend["rafiki-frontend (Remix/React)"]:::frontend
    end

    %% Services Layer
    subgraph "Services" 
        direction TB
        AuthService["rafiki-auth (GNAP Authorization Server)"]:::service
        BackendService["rafiki-backend (GraphQL + REST + ILP)"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        TB["TigerBeetle Cluster"]:::datastore
        Postgres["Postgres Database"]:::datastore
        Redis["Redis Cache"]:::datastore
        ILPNet["ILP Network (External Peers & Payment Pointers)"]:::external
    end

    %% Telemetry Layer
    subgraph "Telemetry"
        direction TB
        OTel["OpenTelemetry Collector"]:::telemetry
        Prometheus["Prometheus"]:::telemetry
        Grafana["Grafana"]:::telemetry
    end

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD"
        direction TB
        RafikiHelm["Helm Charts: rafiki umbrella"]:::infra
        TBHelm["Helm Chart: tigerbeetle"]:::infra
        TelemetryLocal["Local Telemetry Stack"]:::infra
        MockASE["Local Mock ASE"]:::infra
        PostgresChart["Postgres Chart"]:::infra
        RedisChart["Redis Chart"]:::infra
        CICDRafiki["CI/CD: .github/workflows/rafiki"]:::infra
        ActionImagePush["Action: image-push"]:::infra
        ActionManifestPush["Action: manifest-push"]:::infra
    end

    %% Flows
    Browser -->|"Admin UI Requests"| Frontend
    ThirdParty -->|"API Calls (GraphQL/REST/SPSP)"| BackendService
    Frontend -->|"GraphQL/REST"| BackendService
    BackendService -->|"Token Introspection"| AuthService
    BackendService -->|"Ledger Ops"| TB
    BackendService -->|"Read/Write Config"| Postgres
    BackendService -->|"Cache/Lock"| Redis
    BackendService -->|"ILP/SPSP Payments"| ILPNet
    AuthService -->|"Store Grants & Tokens"| Postgres

    %% Telemetry Flows
    BackendService -->|"Traces/Metrics"| OTel
    AuthService -->|"Traces/Metrics"| OTel
    OTel -->|"Metrics"| Prometheus
    OTel -->|"Dashboards"| Grafana

    %% Infrastructure Relations (no arrows, grouping)
    RafikiHelm --- TBHelm
    RafikiHelm --- PostgresChart
    RafikiHelm --- RedisChart
    TelemetryLocal --- OTel
    MockASE --- Frontend

    %% Click Events
    click AuthService "https://github.com/interledger/rafiki/tree/main/packages/auth/"
    click BackendService "https://github.com/interledger/rafiki/tree/main/packages/backend/"
    click Frontend "https://github.com/interledger/rafiki/tree/main/packages/frontend/"
    click RafikiHelm "https://github.com/interledger/rafiki/tree/main/infrastructure/helm/rafiki/"
    click TBHelm "https://github.com/interledger/rafiki/tree/main/infrastructure/helm/tigerbeetle/"
    click TelemetryLocal "https://github.com/interledger/rafiki/tree/main/localenv/telemetry/"
    click MockASE "https://github.com/interledger/rafiki/tree/main/localenv/mock-account-servicing-entity/"
    click PostgresChart "https://github.com/interledger/rafiki/blob/main/infrastructure/helm/rafiki/charts/postgresql-*.tgz"
    click RedisChart "https://github.com/interledger/rafiki/blob/main/infrastructure/helm/rafiki/charts/redis-*.tgz"
    click CICDRafiki "https://github.com/interledger/rafiki/tree/main/.github/workflows/rafiki/"
    click ActionImagePush "https://github.com/interledger/rafiki/tree/main/.github/actions/image-push"
    click ActionManifestPush "https://github.com/interledger/rafiki/tree/main/.github/actions/manifest-push"

    %% Styles
    classDef frontend fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32;
    classDef service fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
    classDef datastore fill:#fff3e0,stroke:#ef6c00,color:#e65100;
    classDef telemetry fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c;
    classDef external fill:#eceff1,stroke:#607d8b,color:#37474f;
    classDef infra fill:#fafafa,stroke:#9e9e9e,color:#616161;
```
