Architecture

Network Topology

Production Deployments (BitMacro)

Component	URL	Hosting
`relay-panel`	`https://relay-panel.bitmacro.io`	Vercel
`relay-api` (Web Server)	`https://relay-api.bitmacro.io`	Vercel
`relay-connect-web`	Subdomain or path	Vercel / self-hosted
`relay-agent` (Relay Server Agent)	`https://<operator-endpoint>`	Operator VPS / local hardware
Supabase	Internal	Supabase Cloud

Network Requirements

The Relay Server Agent must be reachable by the Web Server (Vercel egress).
If the agent runs on a LAN, expose it via tunnel: WireGuard + Nginx Proxy Manager, Cloudflare Tunnel, or ngrok.
relay-panel only needs access to relay-api. Zero direct access to agents or Supabase.
relay-connect-web proxies all /signer/* calls server-side — the browser never holds RELAY_API_KEY.

Connection Flow

Authentication Layers

Layer 1 — User Identity (relay-panel)

Provider	Mechanism
GitHub OAuth	NextAuth.js v5
Session ID	`providerAccountId` (numeric GitHub ID) stored as `token.providerUserId` → `session.user.id`

session.user.id becomes X-Provider-User-Id on every server-side call to relay-api.

Layer 2 — Panel → Web Server

Header	Value	Scope
`X-API-Key`	`process.env.RELAY_API_KEY`	All requests from panel
`X-Provider-User-Id`	GitHub numeric ID	Filters `relay_configs` rows by user

Alternative for clients with a NextAuth session: Authorization: Bearer <JWT> decoded via JWT_SECRET.

Layer 3 — Web Server → Relay Server Agent

v0.2 (multi-relay): Bearer token per relay instance, stored in RELAY_INSTANCES[].token and mirrored in relay_configs.token. Path prefix: /:relayId/.
v0.1 (legacy): Single RELAY_AGENT_TOKEN env var; no path prefix.
/health — no auth required on any version.

State Store (Supabase)

All persistent state lives in Supabase. The Relay Server Agent is completely stateless.

`relay.relay_configs`

Column	Type	Description
`id`	uuid	PK — `gen_random_uuid()`
`name`	text	Display name
`endpoint`	text	Agent base URL
`token`	text	Bearer token for agent
`agent_relay_id`	text	Logical relay ID for multi-relay agent (v0.2)
`provider_user_id`	text	GitHub user ID (NextAuth)
`user_id`	uuid	Nullable, legacy

Index: idx_relay_configs_provider_user_id

`relay.nip46_sessions`

Sessions for NIP-46 pairing: links provider_user_id, relay_config_id, app pubkey, bridge_wss, pairing_secret, and status.

Status	Meaning
`pending`	URI generated, signer not yet paired
`active`	Pairing confirmed via `POST /signer/session/:id/complete`
`revoked`	Manually revoked

Migrations:

20260324140000_relay_nip46_sessions.sql — table creation
20260325130000_relay_nip46_sessions_grants.sql — PostgREST role grants (anon / authenticated / service_role); required to avoid 42501 on INSERT from relay-api

Request Trace: Panel → Stats

Environment Variables

relay-agent (Relay Server Agent)

Variable	Description
`RELAY_AGENT_TOKEN`	(v0.1) Single Bearer token
`RELAY_INSTANCES`	(v0.2) JSON array: `[{id, token, strfryConfig, strfryDb, whitelistPath?}]`
`ALLOWED_ORIGINS`	CORS origins; default includes `relay-panel.bitmacro.io`

Example RELAY_INSTANCES:

[
  { "id": "public",  "token": "tok_pub",  "strfryConfig": "/etc/strfry-public.yml",  "strfryDb": "/var/lib/strfry/public.lmdb"  },
  { "id": "private", "token": "tok_priv", "strfryConfig": "/etc/strfry-private.yml", "strfryDb": "/var/lib/strfry/private.lmdb" },
  { "id": "paid",    "token": "tok_paid", "strfryConfig": "/etc/strfry-paid.yml",    "strfryDb": "/var/lib/strfry/paid.lmdb"   }
]

relay-api (Web Server)

Variable	Description
`RELAY_API_KEY`	Shared key with relay-panel and relay-connect-web
`JWT_SECRET`	NextAuth JWT decode
`SUPABASE_URL`	Supabase project URL
`SUPABASE_SERVICE_ROLE_KEY`	Full access to `relay` schema

relay-panel

Variable	Description
`NEXTAUTH_SECRET`	NextAuth secret
`GITHUB_CLIENT_ID`	GitHub OAuth app
`GITHUB_CLIENT_SECRET`	GitHub OAuth secret
`NEXT_PUBLIC_API_URL`	Web Server base URL
`RELAY_API_URL`	Server-side override (avoids cold-start latency)
`RELAY_API_KEY`	Shared with relay-api

relay-connect-web

Variable	Description
`RELAY_API_URL`	Web Server base URL
`RELAY_API_KEY`	Shared key
`SIGNER_PROVIDER_USER_ID`	GitHub ID for the operator account
`NEXT_PUBLIC_RELAY_BRIDGE_WSS`	Force NIP-46 bridge `wss://`
`NEXT_PUBLIC_NIP07_METADATA_RELAYS`	Comma-separated relays for kind 0 after NIP-07
`NEXT_PUBLIC_RELAY_CONFIG_ID`	Pin a specific `relay_configs` UUID
`SIGNER_PROXY_TIMEOUT_MS`	Proxy timeout (ms)

CORS and security

Surface	Notes
relay-agent	CORS may allow `https://relay-panel.bitmacro.io` and `http://localhost:3000` for testing; the panel does not call the agent directly in production.
relay-panel	Session cookies on its own origin; all relay-api calls are server-side.
relay-api	Panel and connect proxies call from servers, not from arbitrary browser origins exposing secrets.

Secrets:

Never ship RELAY_API_KEY to the browser; relay-connect-web only attaches it on Next.js server routes.
Pairing for NIP-46 uses a per-session pairing_secret verified on POST /signer/session/:id/complete.

End-to-end docs map

Audience	Where to start
Operators (terminal-free relay ops)	Product landing and relay-panel
Full stack (marketing site → connect → API → agent)	This docs section (`/relay-manager/docs`)
Integrators	HTTP APIs, NIP-07, NIP-46

Architecture

On this page