Environment Configuration Reference

This document describes the correct environment configuration for dev and production deployments.

Environment Overview

Configuration Locations

Development Environment

Production Environment

Critical Configuration Rules

1. Convex URL Must Match Across Components

For each environment, the Convex URL must be identical in:

• The web app (NEXT_PUBLIC_CONVEX_URL)
• The API (CONVEX_URL)

Dev: Both must use insightful-bison-499 Prod: Both must use hearty-shrimp-267

2. WorkOS Client ID Must Match Across Components

For each environment, the WorkOS Client ID must be identical in:

• The web app (WORKOS_CLIENT_ID)
• The API (WORKOS_CLIENT_ID)
• The Convex deployment environment variables (WORKOS_CLIENT_ID)

Dev and Prod use different WorkOS Client IDs - never mix them.

3. Convex Schema Must Be Synced

After code changes that modify Convex functions or schema:

# Sync dev Convex
CONVEX_DEPLOYMENT=dev:insightful-bison-499 npx convex dev --once

# Deploy to prod Convex
npx convex deploy -y

Verification Commands

Check Dev Convex Environment Variables

CONVEX_DEPLOYMENT=dev:insightful-bison-499 npx convex env list

Check Prod Convex Environment Variables

CONVEX_DEPLOYMENT=prod:hearty-shrimp-267 npx convex env list

Check Cloudflare Worker Secrets (Production API)

npx wrangler secret list --name transcribe-api

Monitor Dev API Logs

pnpm dev:api
# In another terminal, check logs in the wrangler output

Monitor Production API Logs

npx wrangler tail transcribe-api --format=pretty

Monitor Convex Logs

# Dev
CONVEX_DEPLOYMENT=dev:insightful-bison-499 npx convex logs

# Prod
npx convex logs --prod

Troubleshooting

Dashboard Stats Not Updating

1. Check API is hitting correct Convex: Look for POST /v1/history 201 Created in API logs
2. Check Convex URL alignment: Ensure web app and API use same Convex deployment
3. Check Convex schema is synced: Run npx convex dev --once (dev) or npx convex deploy (prod)
4. Check WorkOS Client ID alignment: All three components must use the same client ID for the environment

Auth Errors ("no applicable key found in JSON Web Key Set")

• WorkOS Client ID mismatch between API and Convex deployment
• Verify all components use the same WorkOS Client ID for that environment

History Saving But Stats Not Showing

• Convex URL mismatch: API saving to different Convex than web app is querying
• Verify CONVEX_URL in API matches NEXT_PUBLIC_CONVEX_URL in web app

Desktop App Configuration

The desktop app:

• Dev build: Connects to localhost:8787 (local API)
• Production build: Connects to https://api.transcribe.dev (production API)

The desktop app does NOT connect directly to Convex - all data flows through the API.