Packages overview

backend/packages/ holds twenty packages in two scopes.

Two scopes

	`@perform/*`	`@repo/*`
Origin	Written for this API	Ported from the web app’s server tier
Config	Receives values as arguments	Reads `process.env` directly
Build	`tsc -p tsconfig.json`	`tsup` (bundled ESM with type declarations)
Imports inside the package	Relative imports end in `.js` (NodeNext)	Extensionless imports (bundler resolution)
How core-api resolves it for types	`tsconfig.base.json` maps `@perform/` to `packages//src/index.ts`	Through the package’s built `dist`
Logger	A pino `Logger` passed in	`@repo/logs` (consola)
Database access	A `PrismaClient` passed in	The `db` singleton from `@repo/database`

The ported packages kept their @repo/* names so their internal imports did not have to change. pnpm does not care about the scope prefix.

All packages

Package	Purpose	Documented on
`@perform/config`	`defineEnv`, env loading and validation	config and utils, Configuration
`@perform/db`	Migrations, seed, re-export of the Prisma client	Database packages
`@perform/errors`	`AppError`, error and not found middleware	errors and types, Responses and errors
`@perform/logger`	pino logger, HTTP logger	Observability
`@perform/observability`	Request id, health, readiness, metrics	Observability
`@perform/queue`	BullMQ factory and queue names	Queues and jobs
`@perform/security`	HMAC signing, nonce store, replay protection	Service auth
`@perform/smartsend`	SmartSend WhatsApp API client	smartsend
`@perform/types`	Shared constants and types	errors and types
`@perform/mcp-tools`	MCP tool definitions and automation client	MCP
`@repo/api`	Hono app, oRPC router and procedures	api
`@repo/auth`	better-auth instance and its hooks	auth, Authentication
`@repo/database`	Prisma client, generated types, auth tier queries	Database packages
`@repo/i18n`	Locale config and translation files	Server i18n
`@repo/logs`	consola logger, `logError`, `serializeError`	Observability
`@repo/mail`	`sendEmail`, templates, provider	Mail
`@repo/notifications`	Coach in-app and email notifications	Notifications and push
`@repo/payments`	Plan catalog, Polar provider, plan resolution	payments, Billing and plan limits
`@repo/storage`	Avatar and logo storage	Storage and uploads
`@repo/utils`	Base URL helpers, password schema	config and utils

Dependency direction

Rules that follow from it:

Packages never import from apps/core-api. When a package needs something the app owns, the app passes it in or the package publishes an event the app listens to. publishSubscriptionChange in @repo/payments is the example.
@repo/auth reaches core-api’s domain tables through @repo/database’s client (for staff seats and studio archiving), and reaches core-api’s HTTP API through a signed request (provisionCoach).
@perform/types and @repo/logs are at the bottom and import nothing from the workspace.

Building

Turbo builds packages in dependency order ("dependsOn": ["^build"]), and typecheck and test also depend on ^build.

pnpm build                                # everything
pnpm --filter @repo/database build        # one package
pnpm typecheck                            # Turbo builds dependencies first, then type checks

Running a package’s own script with --filter (for example pnpm --filter @perform/core-api typecheck) calls tsc directly and does not build dependencies first.

Stale builds

@repo/* packages are consumed from dist. A source change in one is invisible to core-api until the package is rebuilt. Typical symptoms after pulling:

Error in core-api	Rebuild
`Property 'someModel' does not exist on type 'PrismaClient'`	`pnpm --filter @repo/database build`
A missing queue name on `PerformQueue`	`pnpm --filter @perform/queue build`
A missing method on `SmartSendClient`	`pnpm --filter @perform/smartsend build`
Old email text	`pnpm --filter @repo/i18n build`

@perform/* packages resolve to source for types but to dist at runtime (their package.json main points at dist), so they need a build before node dist/server.js or a tsx run sees a change.

Conventions for packages

A package exports a barrel from src/index.ts. Consumers import the package name, never a deep path.
@perform/* packages take configuration as arguments and have no side effects at import.
Some @repo/* packages do have import side effects. @repo/database creates its Prisma singleton and throws if DATABASE_URL is unset. @repo/api’s backend-config.ts validates env at import. Keep that in mind when importing one in a test.
Dependency versions are pinned exactly in the ported packages.

Adding a package

Create the folder

packages/<name>/ with package.json, tsconfig.json and src/index.ts. Copy the config from a neighbour in the same scope. New code written for the API belongs in @perform/*.

Set the entry points

"type": "module", and main, types and exports pointing at dist.

Add it as a dependency

In the consumer’s package.json as "workspace:*", using the pnpm CLI.

Build once

pnpm install, then pnpm --filter <package> build.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

Packages overview

Two scopes

All packages

Dependency direction

Building

Stale builds

Conventions for packages

Adding a package

​Two scopes

​All packages

​Dependency direction

​Building

​Stale builds

​Conventions for packages

​Adding a package

Two scopes

All packages

Dependency direction

Building

Stale builds

Conventions for packages

Adding a package