Package Boundaries

This page documents the shared packages under packages/ and the boundaries they enforce.

@veref/contracts

Shared product contracts and schemas.

• Zod schemas for request payloads
• shared TypeScript types for recruiter views, dashboard data, ops actors, and workflow records
• source of truth for cross-surface payload shape

Use this package when two or more surfaces need to agree on data shape.

@veref/workflows

Workflow and preview helpers.

• recruiter dashboard snapshot builders
• recruiter workspace snapshot builders
• ops feed and message preview builders
• reference-request record helpers
• agent action preview logic

This package expresses the operating model and sample workflow state used across browser, desktop, and API surfaces.

@veref/db

Prisma and database access package.

• Prisma schema
• generated Prisma client export
• database client setup

This is the persistence boundary. API services should use it rather than owning raw schema setup themselves.

@veref/comms

Messaging adapter package.

• Resend email integration
• Twilio SMS integration
• preview-mode fallback when providers are not configured

This package owns outbound communication behavior for reference workflows.

@veref/llm

Hosted LLM integration package.

• OpenRouter client
• configured versus unconfigured behavior
• simple completion helper

This package keeps hosted model wiring outside the API controllers and app surfaces.

@veref/auth

Auth and tenant helper package.

• Clerk env detection
• tenant membership access checks
• role ranking

This package owns auth-adjacent shared logic, not the full app router integration itself.

@veref/desktop-bridge

Electron bridge package.

• preload and main-process contracts
• runtime info shape
• skill catalog shape
• local agent probing
• workspace link health detection

Anything that crosses the Electron boundary should go through this package.

@veref/ui

Shared React UI package.

• recruiter workspace surface
• marketing and docs-adjacent shared UI
• style module exports used by browser and desktop surfaces

This package should stay focused on reusable presentation, not app-specific routing or API calls.

Boundary rules

• put cross-surface data shape in @veref/contracts
• put reusable workflow state and preview composition in @veref/workflows
• put provider integration code in the specific adapter package
• keep app-specific routing and page composition inside the relevant apps/* surface
• keep docs content in apps/docs, not inside shared packages

Current package graph in practice

• apps/app, apps/web, and apps/desktop consume shared UI
• apps/app and apps/desktop consume workflow snapshots
• apps/api consumes contracts, workflows, db, comms, and llm
• apps/desktop consumes desktop-bridge contracts and runtime helpers
• packages/auth depends on @veref/contracts
• packages/workflows depends on @veref/contracts

This is the current boundary line the docs should preserve.