vela-dashboard

Merchant-facing application surface. Both a product surface and a backend boundary that sits between merchants and the protocol.

Purpose and Role

• Merchant wallet auth and email-primary session handling (Better Auth).
• Plan creation, subscription-facing business views, and subscriber management.
• Helius-powered event indexing and webhook delivery.
• Merchant-facing visibility into protocol state (mandates, pulls, streams).
• Billing analytics and revenue dashboards.
• Service binding target for vela-admin backend access.
• Webhook endpoint management (CRUD, secret rotation, delivery retry).

Tech Stack

Technology	Version	Purpose
Vite	latest	Build tool (SPA mode)
React	19.x	UI library
Hono	4.12.x	API layer (Cloudflare Worker)
Better Auth	1.5.x	Authentication (email-primary, Google SSO, SIWS)
Drizzle ORM	0.45.x	Database ORM (D1)
Cloudflare D1	GA	SQLite database (merchant data, sessions, analytics)
Cloudflare KV	—	Session storage, caching
Cloudflare Queues	—	Async webhook fan-out
Cloudflare R2	—	File storage (exports, receipts)
TanStack Query	5.95.x	Data fetching/caching
Tailwind CSS	4.2.x	Styling
@vela/sdk	latest	Protocol interactions
helius-sdk	2.2.2	RPC, webhooks, DAS
wrangler	4.78.x	Cloudflare CLI

Directory Structure

vela-dashboard/
├── src/
│   ├── app/                   # React SPA
│   │   ├── components/        # UI components
│   │   │   ├── plans/         # Plan creation and management
│   │   │   ├── subscribers/   # Subscriber views
│   │   │   ├── analytics/     # Billing analytics
│   │   │   ├── webhooks/      # Webhook endpoint management
│   │   │   └── settings/      # Org settings, wallet linking, 2FA
│   │   ├── hooks/             # React hooks for data fetching
│   │   └── pages/             # Route pages
│   ├── worker/                # Hono Worker (backend API)
│   │   ├── index.ts           # Worker entry, Hono app
│   │   ├── auth.ts            # Better Auth configuration
│   │   ├── session.ts         # Session management
│   │   ├── routes/            # API route handlers
│   │   │   ├── plans.ts
│   │   │   ├── subscribers.ts
│   │   │   ├── webhooks.ts
│   │   │   ├── admin.ts       # Admin service binding endpoints
│   │   │   └── checkout.ts    # Checkout session management
│   │   └── middleware/        # Auth, rate limiting, CORS
│   ├── db/                    # Drizzle schema and migrations
│   │   ├── schema.ts          # Drizzle schema definition
│   │   └── migrations/        # SQL migration files
│   └── lib/                   # Shared utilities
├── drizzle.config.ts          # Drizzle Kit configuration
├── wrangler.toml              # Cloudflare Worker config (D1, KV, R2 bindings)
├── vite.config.ts             # Vite build config
└── package.json

Deployment Target

• Railway: Runs React SPA SSR for merchant dashboard.
• Cloudflare Workers: Hono Worker for API backend.
• Cloudflare D1: SQLite database for all merchant data.
• Cloudflare KV: Session storage and caching.
• Cloudflare R2: File storage for exports and receipts.
• Cloudflare Queues: Async webhook event fan-out.

Dependencies

What It Depends On

Dependency	Type	Purpose
@vela/sdk	npm package	Protocol interactions, instruction builders, PDAFactory
Cloudflare D1	Infrastructure	Database
Helius	Infrastructure	RPC, webhooks, DAS API
Better Auth	Library	Authentication

What Depends on It

Consumer	How	What They Use
vela-admin	Service binding	Backend API access, D1 operations
vela-checkout	API proxy	Checkout session creation
vela-portal	API proxy	Checkout session for plan switching

Current Status

• v1.8 complete: Multi-token support, plan upgrades, webhook management.
• Auth: Email-primary (Better Auth) with Google SSO and SIWS wallet linking.
• Webhooks: Full endpoint management with HMAC-SHA256 delivery and retry.

Notable Design Decisions

Email-Primary Auth (v1.3)

Pivoted from wallet-first to email-primary auth in v1.3. Merchants need traditional login, team access, and session persistence. Wallets are treasury tools, not identity providers.

Service Binding Target

The dashboard Worker exposes internal API routes that vela-admin accesses via Cloudflare service binding. Admin never directly accesses D1 — all database operations go through the dashboard.

Dual Runtime (Railway + Cloudflare)

The React SPA runs on Railway for SSR while the API runs on Cloudflare Workers. This split allows the frontend to use Node.js features while the backend leverages Cloudflare's edge network and D1 integration.

D1 Batch API (No Interactive Transactions)

D1 doesn't support interactive transactions. Better Auth and Drizzle use D1's batch() API for atomicity. This is a known limitation accepted during development with a migration path to Postgres at PMF.

Helius Webhook Integration

Real-time on-chain event indexing via Helius Enhanced webhooks. Mandate creation, pull execution, cancellation, stream events, and upgrade events all trigger dashboard updates.