Workspace App

apps/workspace is the internal-only Next.js app deployed at workspace.matters.ai. It hosts every admin module, content studio, and operational tool the team uses.

Surfaces#

The workspace lives entirely under the (workspace) route group at apps/workspace/app/(workspace)/**. The route group is unwrapped at URL level, so a file at apps/workspace/app/(workspace)/webinars/page.tsx serves workspace.matters.ai/webinars.

A live, code-derived permission matrix lives at Workspace → RBAC.

Auth model — three layers#

1. Edge middleware (apps/workspace/proxy.ts):

   • Clerk clerkMiddleware() wraps every request.
   • Host gate first: requests whose host isn't in ALLOWED_HOSTS (workspace.matters.ai, plus localhost/127.0.0.1/::1) get a bare 404 before any auth runs.
   • Public routes (/auth/*, /api/auth/2fa/*, /api/webhooks/clerk, /api/health) pass through. /api/auth/2fa/* is public because it runs during the login step, before the session is fully trusted; its handlers self-enforce Clerk auth().
   • Everything else requires both a valid Clerk session and an email whose domain is in @matters/auth's ALLOWED_EMAIL_DOMAINS. Failures → 401/403 (API) or /auth/login redirect (page).

2. Layout defense-in-depth (apps/workspace/app/(workspace)/layout.tsx):

   • Re-runs the allowlist check using Clerk's currentUser().
   • Fetches RBAC roles via getCurrentUserRoles() so the shell can hide unauthorized modules from the sidebar.
   • Redirects to /auth/sign-out?error=domain_restricted if a session somehow slipped past the middleware.

3. Per-route RBAC: every API handler that reads or mutates data calls checkRole(...) or hasPermission(roles, ...) from lib/auth/rbac.ts / lib/auth/rbac-shared.ts. There are 13 roles and 55 permissions. See RBAC for the full matrix.

Why a separate Next.js app?#

The workspace previously lived at matters.ai/workspace. Splitting it onto its own subdomain delivers four wins:

• Isolated deploy. Marketing changes don't redeploy admin code; admin changes don't risk marketing uptime.
• Smaller public bundle. The public app no longer carries workspace components, RBAC, or Clerk-heavy admin pages.
• Cookie/CSP isolation. Workspace can set stricter CSP than marketing without breaking embed widgets on landing pages.
• Cleaner mental model. "Anything at workspace.matters.ai is internal" is a one-sentence security boundary that ops, legal, and on-call all understand.

Local development#

pnpm --filter @matters/workspace dev   # serves on :4001

Requires the same .env.local at repo root that the public site uses. The workspace app reads all CLERK_*, MONGODB_*, WORDPRESS_*, MUX_*, SALESFORCE_*, etc. via the shared @matters/lib/config/env Zod schema.

Clerk's session cookie needs Domain=.matters.ai set in the Clerk dashboard for production SSO to work across matters.ai ↔ workspace.matters.ai. Locally that's irrelevant; both apps share localhost.