Admin Dashboard

The admin dashboard (apps/admin/) is a standalone Nuxt 3 application for platform-level administration. It is separate from the tenant-facing web app and provides tools for managing users, organizations, abuse detection, and delivery monitoring.

Architecture

The admin app shares the same Convex backend as the main web app. It uses platform-admin queries and mutations that are restricted to users with the platform-admin role in the database.

Authentication Flow

Auth Proxy Pattern

The admin app proxies authentication requests through a same-origin server route (server/api/auth/[...].ts) to avoid CORS issues. This route forwards requests to the Convex site URL, strips problematic headers (Host, Connection), and handles Set-Cookie domain adjustments for local development.

Browser → /api/auth/* → Nuxt server route → Convex site URL → response proxied back

Token Management

The lib/convex-auth.ts module manages JWT tokens for Convex:

• Caches the current token to avoid unnecessary auth calls
• Implements a 60-second refresh buffer (refreshes before expiry)
• Provides getConvexAuthToken() for the Convex client's auth callback

Pages

Middleware

Two middleware layers protect admin routes:

1. auth.ts — redirects unauthenticated users to /login (with redirect query param)
2. platform-admin.ts — queries api.platformAdmin.isPlatformAdmin and redirects non-admins to /unauthorized

Composables

Query Usage Pattern

const { data: organizations, isLoading } = useConvexQuery(
  api.platformAdmin.listOrganizations,
  () => ({ status: selectedStatus.value })
)

The args factory function is deep-watched — when selectedStatus changes, the query automatically re-subscribes with new arguments.

Environment Variables

Set in apps/admin/.env:

Security

The admin app is configured with strict security headers via nuxt-security:

• CSP — strict script-src, object-src: 'none', Convex URL in connect-src
• HSTS — enabled with long max-age
• X-Frame-Options — DENY (prevents embedding)
• Referrer-Policy — strict-origin-when-cross-origin

Key Files