Skip to Content
Deployment & Operations

Deployment & Operations

This page documents the current build and operational expectations for each shipped surface.

Repo-wide build contract

Top-level commands:

bun run typecheck
bun run test
bun run build

These map to Turborepo tasks across the workspace.

Surface build and run expectations

apps/app

  • bun run dev:app
  • bun run --filter @veref/app build
  • Next.js recruiter workspace deployment

apps/web

  • bun run dev:web
  • bun run --filter @veref/web build
  • Next.js public marketing deployment

apps/docs

  • bun run dev:docs
  • bun run --filter @veref/docs build
  • static-export-friendly Nextra docs deployment because apps/docs/next.config.mjs sets output: "export"

apps/api

  • bun run dev:api
  • bun run --filter @veref/api build
  • NestJS API process listening on PORT or 8787

apps/desktop

  • bun run dev:desktop
  • bun run --filter @veref/desktop build
  • Electron packaging and local workstation runtime
  • native shell for https://app.veref.work; local app/API targets require explicit VEREF_DESKTOP_APP_URL and VEREF_DESKTOP_API_URL

apps/mobile

  • bun run dev:mobile
  • bun run --filter @veref/mobile build
  • current build script explicitly says to use EAS for production mobile builds

apps/extension

  • bun run dev:extension
  • bun run --filter @veref/extension build
  • bun run --filter @veref/extension package
  • Plasmo extension packaging flow

apps/cli

  • bun run dev:cli
  • bun run --filter @verefwork/cli build
  • public npm package: @verefwork/cli
  • manual publish workflow: .github/workflows/publish-cli.yml
  • distributed as a bundled Node executable, not TypeScript source

Operational dependencies

Database

  • Postgres reachable through DATABASE_URL
  • Prisma client generated before API build and typecheck in @veref/db

Auth

  • Clerk only becomes fully configured when both publishable and secret keys are present
  • API key hashing depends on API_KEY_PEPPER; changing it invalidates verification for existing keys

Hosted AI

  • OpenRouter depends on OPENROUTER_API_KEY
  • base URL defaults to the OpenRouter API endpoint unless overridden
  • chat and extraction models default to google/gemini-3-flash-preview,openrouter/free unless overridden

Messaging

  • Resend requires RESEND_API_KEY
  • Twilio requires account SID, auth token, and messaging service SID

Desktop runtime

  • local claude and codex binaries if you want live availability checks
  • healthy .claude and .codex links if you want the desktop skill catalog to match repo state

Desktop notarization

  • macOS release packaging can build DMG/ZIP artifacts without notarization
  • production desktop release readiness requires either APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID, or App Store Connect API key credentials through APPLE_API_KEY, APPLE_API_KEY_ID, and APPLE_API_ISSUER
  • the first production desktop release is not ready to distribute until notarization is configured and a packaging run no longer reports skipped notarization

Deployment notes by surface

  • browser surfaces depend on the NEXT_PUBLIC_* URLs matching where sibling surfaces actually run
  • the published CLI defaults to https://api.veref.work and https://app.veref.work
  • local or staging CLI runs can override URLs through flags, VEREF_API_URL, or VEREF_APP_URL
  • the extension should be configured to open the correct recruiter app URL through PLASMO_PUBLIC_APP_URL
  • docs can stay public while contributor-only guidance remains protected editorially rather than technically

Operational reality of preview mode

Several surfaces can still build or run without every provider configured. That is useful for onboarding, but production-style behavior still depends on real environment configuration and reachable services.

Ops routes are not silent stubs anymore. They require Prisma-backed persistence unless VEREF_ENABLE_PREVIEW_FALLBACK=1 is intentionally enabled for local development.

TroubleshootingArchitecture