Smart Router Dashboard

July 8, 2026 · View on GitHub

Smart Router Dashboard

The observability dashboard for the Smart Router — every value on screen maps to a real Prometheus series or renders an honest empty state. No invented numbers, ever.

Quick Start · How it works · Pages · Authentication · Development · Releases · License · Contributing · Security

What is Smart Router Dashboard

Live metrics, honestly sourced — KPIs, RPS, latency, error breakdowns, provider selection scores: all straight from the router's smartrouter_* / rpc_endpoint_* Prometheus families. Metric families the router hasn't emitted yet render the design's own empty states and light up automatically when they appear.
Topology-aware — one values file drives both the router and the dashboard, so the Endpoints/Providers pages always reflect the running configuration.
Live test console — fire requests at any chain × interface the router serves, straight from the browser, with a full method catalog generated from the lava-specs repo (126 chains, jsonrpc/rest/tendermint/grpc, archive/debug/trace tiers).
Self-contained — make up gives you router + Prometheus + api + web from nothing. No accounts, no cloud, optional auth.
Optional authentication — AUTH_MODE=enabled adds Auth.js sign-in (email+password + Google/GitHub/Discord) backed by Postgres. Default is open (disabled) for private deployments.

Repo layout: a pnpm/TypeScript monorepo — apps/api (Fastify 5 Prometheus proxy) + apps/web (Next.js 16) + packages/shared + packages/db. Everything runs from the repo root.

Quick Start

make up        # router + Prometheus + api (:8000) + web (:3000) + logs (Grafana :3001), detached
make up-cache  # ...plus the smart-router cache sidecar (:20100, metrics :5555)
make ps        # show what's running
make down      # stop everything

UI → http://localhost:3000 · API → http://localhost:8000 · Prometheus → http://localhost:9090 · router → http://localhost:3360-3367 (ETH1 · SOLANA · BTC · HYPERLIQUID · COSMOSHUB rest/tendermint/grpc · APT1)

The router pulls the published image (ghcr.io/magma-devs/smart-router:latest) and loads chain specs straight from the lava-specs GitHub repo — no checkout, no volume mounts. The default config is multichain with cross-validation policies enabled; see dev-config/values.yml.

With a router already running on the host's :7779:

docker compose up --build     # dashboard + Prometheus only

Relay cache (optional)

The stack can run the smart-router's RAM relay cache sidecar (mirrors smart-router/docker/docker-compose.cache.yml). It's opt-in behind the cache profile and off by default:

make up-cache
# or: SR_CACHE_BE=cache:20100 docker compose --profile router --profile cache up --build

make up-cache wires the router to the cache via the --cache-be flag (SR_CACHE_BE=cache:20100) — no values.yml edit needed. The cache listens on :20100 and exposes its own Prometheus metrics on :5555 (scraped as the smart-router-cache job). With the profile off, SR_CACHE_BE is empty and the router uses its in-process cache.

How it works

┌─────────────────┐        ┌──────────────────────┐        ┌──────────────┐
│   apps/web      │  REST  │      apps/api        │ PromQL │  Prometheus  │
│   Next.js 16    │───────▶│  Fastify 5 (:8000)   │───────▶│   (:9090)    │
│   (:3000)       │        │  stateless proxy —   │        └──────┬───────┘
│                 │        │  every endpoint maps │               │ scrape
│  SWR-style      │        │  to real PromQL      │        ┌──────┴───────┐
│  hooks + charts │        └──────────┬───────────┘        │ Smart Router │
└─────────────────┘                   │ reads              │  (:7779)     │
                                      ▼                    └──────────────┘
                            mounted values.yml
                       (same file drives the router)

The api is a stateless Prometheus proxy — no database on the metrics path, per-route caching, unbacked values returned as null (never invented).
The web is runtime-configurable — one published image points at any api host via DASHBOARD_API_URL.
AUTH_MODE=enabled adds a Postgres users store + HS256 JWT gate on /api/* — see Authentication.

Authentication

Two modes via AUTH_MODE (full guide: docs/AUTH.md):

disabled (default) — no login, no database. The dashboard opens straight on Overview. For private/self-hosted deployments.
enabled — Auth.js v5 sign-in backed by Postgres (Drizzle), bcrypt credentials + optional Google/GitHub/Discord (each button appears only when its client id/secret pair is set), HS256 JWT shared between web and api, idempotent ADMIN_EMAIL/ADMIN_PASSWORD bootstrap seed.

AUTH_MODE=enabled AUTH_SECRET=$(openssl rand -base64 32) \
ADMIN_EMAIL=you@example.com ADMIN_PASSWORD=change-me \
  docker compose --profile router --profile auth up -d --build
# sign in at :3000/login with ADMIN_EMAIL / ADMIN_PASSWORD
# (the dev compose ships working defaults — see docs/AUTH.md)

Development

make dev            # hot-reload docker stack (api tsx watch · web next dev · shared tsc --watch)

# or on the host (Node 24 + pnpm 10, needs a Prometheus at PROMETHEUS_URL):
cp .env.example .env   # optional — every var has a compose default
pnpm install
pnpm --filter @sr/shared build && pnpm --filter @sr/db build
pnpm dev            # api :8000, web :3000
pnpm -r typecheck && pnpm -r test

The repo pins Node via .nvmrc (nvm use) and ships an .env.example documenting every runtime knob — copy it to .env for host dev, or read it as the reference for self-hosting one published image against your own router.

Project structure:

apps/
  api/            Fastify 5 REST api — Prometheus proxy + optional auth
  web/            Next.js 16 App Router frontend
packages/
  shared/         Domain types, PromQL builders, constants
  db/             Drizzle schema + Postgres client (AUTH_MODE=enabled only)
dev-config/       values.yml driving both router and dashboard
docs/             AUTH.md · METRICS-MAPPING.md
docker-compose.yml / docker-compose.dev.yml / Makefile

See CLAUDE.md for the endpoint reference, env vars, and gotchas.

Testing & CI

pnpm lint            # eslint (flat config) across the whole monorepo
pnpm -r typecheck    # strict TS across every package
pnpm -r test         # vitest — api routes, PromQL builders, config parser, auth, chain catalog
pnpm format          # prettier --write (format:check to verify only)

Every push and PR to main runs the Quality Gate: lint + typecheck + the full vitest suite, plus a chain-map drift check that regenerates the chain catalog from the live lava-specs repo and fails if the committed map is stale. Renovate-style dependency bumps arrive via Dependabot (npm + GitHub Actions, weekly).

When NODE_ENV isn't production, the api also serves an interactive OpenAPI 3.1 explorer at /docs (raw spec at /docs/json) covering every api route — see CLAUDE.md for the full endpoint reference.

Releases & images

Changes are tracked in CHANGELOG.md. Versioning is driven by the root VERSION file: pushes to main run the Build and Push Images workflow, which tags and publishes

ghcr.io/magma-devs/smart-router-dashboard/backend — the Fastify api (apps/api)
ghcr.io/magma-devs/smart-router-dashboard/frontend — the Next.js web (apps/web)

Set DASHBOARD_API_URL on the web container at runtime to point one published image at any api host.

docker pull ghcr.io/magma-devs/smart-router-dashboard/backend:latest
docker pull ghcr.io/magma-devs/smart-router-dashboard/frontend:latest

Issues — bugs and feature requests
Smart Router — the router this dashboard observes