Riverrun Backend

Push notification service for Riverrun, a self-custodial mobile trading app for Hyperliquid DEX.

Overview

This backend service provides push notifications for the Riverrun mobile app. It subscribes to Hyperliquid's WebSocket feed and sends notifications to users when their orders are filled.

Note: This backend is optional. The Riverrun mobile app works fully without it — you just won't receive push notifications.

Features

• Device token registration for iOS and Android
• Real-time order tracking via Hyperliquid WebSocket
• Push notifications for order fills (via Expo)
• Notification deduplication
• Health check endpoints

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Hyperliquid   │────▶│  Notification    │────▶│    Expo     │
│   WebSocket     │     │    Service       │     │   Push      │
└─────────────────┘     └──────────────────┘     └─────────────┘
                               │
                               ▼
                        ┌─────────────┐
                        │  DynamoDB   │
                        └─────────────┘

Packages

Package	Description
@riverrun-backend/notification-service	Main HTTP API service
@riverrun-backend/hyperliquid	Hyperliquid WebSocket subscription manager
@riverrun-backend/db	DynamoDB repository layer
@riverrun-backend/api-common	Shared middleware and routes
@riverrun-backend/common	Logging utilities

Tech Stack

• Runtime: Node.js 22+
• Framework: Hono (lightweight web framework)
• Database: AWS DynamoDB
• Push Notifications: Expo Server SDK
• WebSocket: Hyperliquid API
• Language: TypeScript (strict mode)
• Package Manager: pnpm 10+

Getting Started

Prerequisites

• Node.js 22+
• pnpm 10+
• AWS Account (for DynamoDB) or DynamoDB Local for development

Installation

# Clone the repository
git clone https://github.com/sadcoderlabs/riverrun-backend.git
cd riverrun-backend

# Install dependencies
pnpm install

# Build all packages
pnpm build

Environment Variables

Create a .env file based on the example:

# AWS Region for DynamoDB
AWS_REGION=ap-northeast-1

# Server port
PORT=3000

# Hyperliquid WebSocket URL
HYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws

# For local development with DynamoDB Local
DYNAMODB_ENDPOINT=http://localhost:8000

# Log level (debug, info, warn, error)
LOG_LEVEL=info

# Environment (development, production)
NODE_ENV=development

Database Setup

Create the required DynamoDB tables:

pnpm --filter @riverrun-backend/db db:create-tables

Running Locally

# Development mode with hot reload
pnpm --filter @riverrun-backend/notification-service dev

# Production mode
pnpm start-notification-service

The server will start at http://localhost:3000.

Health Check

curl http://localhost:3000/health

API Endpoints

Method	Endpoint	Description
GET	/health	Health check
POST	/devices	Register device token
DELETE	/devices	Unregister device token

Deployment

The repository includes example Kubernetes deployment manifests in deployments/production/. These are provided as reference — you'll need to customize them for your infrastructure:

• Update AWS account IDs
• Configure your own ACM certificates
• Set your domain name
• Adjust resource limits as needed

Development

# Run tests
pnpm --filter @riverrun-backend/notification-service test

# Format code
pnpm format

# Lint
pnpm lint

Related Projects

• Riverrun - Mobile trading app (React Native/Expo)

License

MIT License

Copyright (c) 2026 SadCoderLabs (original Perpetual Protocol team before 2025)

See LICENSE for details.

Contributors

• @vinta
• @opass