Ronin Ecosystem Tracker

System & Architecture Documentation

Understand how RONHUB stitches together raw blockchain data, ML predictions, GraphQL analytics, smart contracts, and Next.js to power the Ronin ecosystem experience. This is a high-level system guide, not a low-level API reference.

High-Level Architecture

The system is intentionally split into specialized services. The frontend talks to a thin edge layer in Next.js, which then fans out to raw data providers, an ML analytics brain, a GraphQL analytics service, and a Go-based application backend.

Frontend Experience

Next.js + React UI, orchestrating analytics, staking, projects, games, collections, snapshot, and multi-send tools.

• Edge API routes under /api/*
• GraphQL client and TanStack Query for rich data states
• Wallet-aware surfaces: authentication, staking, portfolio, snapshotting

Data & Analytics Layer

Raw Data API and ML Analytics API provide cached market data, Dune analytics and model-driven insights.

• 24h cached raw data from Dune & CoinGecko
• Background polling + auto-retraining ML pipeline
• Prediction endpoints consumed by the Analytics page

Core Backend & Contracts

Go REST + GraphQL backend and on-chain contracts for staking, snapshotting and multi-send.

• SIWE + JWT auth at /api/v1/auth/*
• Snapshot lifecycle at /api/v1/snapshots
• GraphQL schema for projects, staking pools and analytics

Analytics Engine & Data Flow

The Analytics page is powered by a three-layer flow: a Raw Data API that caches upstream providers, an ML Analytics API that transforms those signals into predictions, and a thin Next.js edge layer that the React components call.

Raw Data API (v3.0)

Source of truth & 24h cache

• Caches Dune & CoinGecko responses on disk for 24 hours.
• Background refresher keeps cache warm on startup and continuously.
• Serves unmodified JSON frames for downstream consumers.

Key endpoints (no base URL)

GET / – service metadata & status

GET /api/raw/coingecko/ron – RON market data

GET /api/raw/dune/{query_key} – game, network & holder analytics

GET /api/cache/statusPOST /api/cache/refreshGET /api/bulk/all

ML Analytics API (v1.0)

Autonomous prediction engine

• Polls the Raw Data API every ~15 minutes with hash-based change detection.
• Triggers feature engineering and ensemble training when data changes.
• Serves cached predictions and model stats with zero-latency responses.

Prediction & model endpoints

GET /GET /api/healthGET /api/polling/status

GET /api/predictions/game-health – per‑game decline risk & momentum

GET /api/predictions/games-at-riskGET /api/predictions/trending-games

GET /api/models/infoGET /api/bulk/predictions

Next.js Analytics Gateway

Edge-facing API routes

React components never talk directly to Dune or the ML service. Instead, they call internal Next.js API routes that proxy, validate and cache responses.

Frontend-facing endpoints

GET /api/coingecko/ron – cached RON price feed (60s revalidate)

GET /api/dune/games-dailyGET /api/dune/holdersGET /api/dune/ronin-daily

GET /api/dune/nft-collectionsGET /api/ml/predictions

These routes back the Analytics dashboard sections like RON market intelligence, game activity, network dynamics, holder intelligence, DEX activity and NFT marketplace views.

Analytics Page Data Flow Sequence

Loading diagram...

Other Major Experiences

Beyond the Analytics page, RONHUB exposes staking, project discovery, collections, games, and operational tools. Each surface has its own data contracts and backends, but they all follow the same principles: cache at the edge, keep contracts of data clear, and never leak infrastructure complexity into the UI.

Staking Hub

The staking page lists ERC-721 staking pools today (and is designed to support ERC-20 pools next), driven entirely by the GraphQL analytics service.

• Uses hooks like useERC721StakingPools to query GraphQL.
• Infinite scrolling via cursor-based pagination, cached via TanStack Query.
• UI is purely declarative; sort, search and pagination are implemented as GraphQL fields.

GraphQL entrypoint (configured via NEXT_PUBLIC_GRAPHQL_ENDPOINT) is consumed through a shared client and not directly exposed to the browser.

Projects, Games & Collections

Discovery experiences for projects, games and NFT collections rely on the GraphQL backend, plus internal Next.js APIs for wallet-aware NFT data.

• Projects list & detail pages use GraphQL queries (e.g. useInfiniteProjects).
• Wallet NFT inventory is resolved through routes like /api/nfts/all and /api/fetch-owned-collections.
• Games analytics views reuse the same Dune-backed endpoints as the Analytics page.

Snapshot Tool

A multi-step experience that coordinates on-chain snapshot requests with an off-chain worker that prepares downloadable holder files.

1. User configures snapshot type and target contract in the UI.
2. Frontend calls the Snapshot smart contract's createSnapshotRequest function.
3. After a successful transaction, the app calls POST /api/v1/snapshots on the Go backend to register the job.
4. A background worker processes the snapshot and exposes status via GET /api/v1/snapshots and GET /api/v1/snapshots/{id}/status.

The UI never accesses raw storage directly; it only follows an idempotent request ID from chain → backend → downloadable artifact.

Authentication & Accounts

Sign-In With Ethereum (SIWE) for Ronin wallets, backed by short-lived nonces and JWTs, powers authenticated-only features.

• Frontend uses an AuthAPI client to call the Go REST API.
• Endpoints include POST /api/v1/auth/nonce, POST /api/v1/auth/verify, POST /api/v1/auth/logout and GET /api/v1/auth/me.
• Cookies are HTTP-only; JWTs are verified by shared middleware before protected routes run.

Snapshot Tool Request Flow

Loading diagram...

Authentication Flow (SIWE)

Loading diagram...

Resilience, Caching & Design Principles

Every layer is designed to be resilient, observable and predictable: users should see fast dashboards, operators should see clear boundaries and failures should degrade gracefully instead of breaking the experience.

Caching Strategy

• Raw data cached for 24 hours in the Raw Data API.
• Next.js API routes use revalidate: 60 for hot analytics.
• ML predictions are cached on disk and only recomputed when hashes change.

Error Handling & Degradation

• ML polling uses exponential backoff if the Raw Data API is unreachable.
• On restart, the ML API reloads the last champion model to avoid "cold start".
• Frontend surfaces show loading states, toasts and non-blocking warnings instead of failures.

Design & UX Principles

• Use gradients, glassmorphism and motion sparingly to emphasize hierarchy.
• Keep user flows linear: configure → confirm → execute → verify → download.
• Surfacing intent-first copy so users always know what a metric or action means.

Multi-Layer Caching Strategy

Loading diagram...

System overview — last updated 2026-01-14