Admin Dashboard

The nest dashboard (apps/nest/) is a standalone Nuxt 3 application for platform-level administration. It is separate from the tenant-facing web app and provides tools for managing organizations, VPS infrastructure, billing, and platform health.

Architecture

The admin app connects to its own Convex backend (apps/nest-api), which is a separate deployment from the tenant app (apps/api). The control plane manages VPS provisioning, billing, health monitoring, and organization lifecycle.

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 the platformAdmins table and redirects non-admins to /unauthorized

Organization Lifecycle

Organizations follow a state machine managed by the control plane:

States

Admin Actions

• Suspend — Disables routing (org becomes inaccessible), VPS remains running
• Resume — Re-enables routing for a suspended org
• Change tier — Updates tier and queues a VPS resize job if server type differs
• Delete — Queues VPS deletion job, disables routing immediately
• Approve signup — Triggers VPS provisioning for a pending organization
• Reject signup — Sets organization to cancelled status

VPS Provisioning

The control plane manages VPS infrastructure through a job queue system.

Job Types

Jobs are queued in the provisioningJobs table and processed every 1 minute by a cron job.

Create Flow

1. Admin approves signup or payment is confirmed via Stripe webhook
2. Provisioning job queued with type: 'create'
3. Secrets generated: instanceSecret, convexAdminKey, mtaApiKey, mtaWebhookSecret
4. VPS record created in database
5. Hetzner API called to create server with cloud-init userdata
6. Cloud-init installs Docker, writes .env and docker-compose.yml, starts all services
7. Smoke test polls Convex (:3210) and Web (:3000) — up to 5 minutes
8. Routing table entry created (slug → IPv4)
9. Organization marked as active

Available Regions

Per-VPS Stack

Each VPS runs six Docker services via Docker Compose:

Health Monitoring

The control plane runs automated health checks every 5 minutes against all running VPS instances.

Checked Services

Status Determination

Alerting and Auto-Recovery

Health Alert Types

Billing and Invoicing

Pricing Tiers

Stripe Integration

Each tier has a corresponding Stripe Price ID. When a user signs up:

1. Stripe Customer created
2. Stripe Subscription created with payment_behavior: 'default_incomplete'
3. Client secret returned for Stripe Elements payment confirmation
4. On invoice.paid webhook — organization provisioning is triggered automatically
5. On invoice.payment_failed — organization marked as error, user can retry

Invoice Generation

Monthly invoices are generated automatically by a daily cron job:

• Format: INV-YYYYMM-XXXX (e.g., INV-202603-0001)
• Payment terms: 14 days from period start
• Statuses: draft → open → paid / overdue → void
• Overdue detection runs alongside invoice generation

Revenue Dashboard

The /billing page displays:

• MRR — Sum of monthly tier prices for all active organizations
• Total revenue — Sum of all paid invoices
• Open invoices — Count and total amount
• Overdue invoices — Count and total amount

Signup Flow

Self-Service (User-Initiated)

Admin Manual

Admins can create organizations directly from /organizations/new:

1. Enter organization name, slug, owner email
2. Select tier and region
3. Provisioning job queued immediately (no payment step)

Alternatively, admins can approve pending signups from the /waitlist page:

1. Review pending organization details
2. Optionally change the tier
3. Approve — triggers VPS provisioning
4. Reject — sets organization to cancelled with optional reason

Control Plane Backend (apps/nest-api)

The control plane is a separate Convex deployment managing all platform infrastructure.

Key Modules

Cron Jobs

Composables

Query Usage Pattern

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

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

Environment Variables

Admin Dashboard (apps/nest/.env)

Control Plane Backend (nest-api Convex dashboard)

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

Admin Dashboard (apps/nest/)

Control Plane Backend (apps/nest-api/)

Infrastructure (infra/)