Overview

@workspace/training is the product model of Bridge Training: teachers, students, groups, sessions, boards, collections, plans and entitlements, ads, telemetry and usage. It is a pure-TypeScript hexagonal core: the domain layer holds entities, value objects and pure rules; the application layer holds services, input DTOs, query objects and the ports that infrastructure adapters implement. Nothing in the package touches a database, a queue or HTTP.

Runtime dependencies: @workspace/bridge (deal types and rules), @workspace/rich-text (comment and review model), @workspace/shared (logger, time and error helpers), @workspace/i18n and @workspace/i18n-messages (languages and theme labels). No React, no DOM, no vendor SDK.

Quick start

A service is a factory taking its ports; the consuming app passes an adapter and threads a ServiceContext as the last argument of every call.

// Adapters (packages/database) implement the ports; the app wires them once.
export function listGroups(
  deps: GroupsServiceDeps,
  ctx: ServiceContext
): Promise<Group[]> {
  const groups = createGroupsService(deps);
  return groups.list(ctx); // ctx is always the last argument
}

Domain errors are AppError subclasses carrying a stable code; the API translates them at its boundary, the app never sees them.

export async function renameGroup(
  deps: GroupsServiceDeps,
  groupId: string,
  name: string,
  ctx: ServiceContext
) {
  const groups = createGroupsService(deps);
  try {
    return await groups.update(groupId, { name }, ctx);
  } catch (error) {
    if (isAppError(error)) {
      error.code; // => "GROUP_NOT_FOUND"
      error.isExpected; // => true
    }
    throw error;
  }
}

See Usage for the wiring in each app, Service Context for the ctx rule and Errors for the error family.

Sub-path exports

Every symbol is reached through one of the sub-paths of the package exports map. A module's index.ts is its public surface; the other files of the folder are internal.

Rule: a module is imported through its own path; there is no forwarding file. Inside the package, imports are direct relative paths, never the root barrel.

Modules

Each page documents the domain/<module> and application/<module> folders of one module.

Teaching

Plans and billing

Platform

Architecture

Layer first, module second: the lint rule is the layer rule, domain ↛ application ↛ infrastructure. Modules are too intertwined (a session links boards and collections, entitlements govern collections) to be the first boundary.

packages/training/src/
├── domain/
│   ├── shared/              # AppError family, ErrorCode, ServiceContext, languages, localized fields
│   └── <module>/            # entities, value objects, errors, pure rules
├── application/
│   ├── shared/              # QueryObject, Criteria, Projection, pagination, Read/WriteRepository
│   ├── ports/               # cross-cutting ports (queue, event bus, email, storage, tokens…)
│   └── <module>/            # services, input DTOs, query objects
│       └── ports/           # the module's repositories
├── factories/               # (faker, overrides) factories, one per type
└── testing/                 # fakes and mocks of the ports

• The layer rule is linted. A domain file imports sibling domain modules only; an application file imports domain and application; neither imports an infrastructure or UI package, the package's own public entry points, or factories/ outside tests.
• Primitives imported, product model injected. bridge, rich-text and shared are imported directly by anyone. training is reached by infrastructure adapters through its ports, and by the UI through ViewModels built in the apps: no ui-* package imports it.
• Services are plain factories. createXxxService(deps) returns an object of methods; every method acting on a user's data takes ctx: ServiceContext last. Authorization is decided by the app before the call.
• One regime per service. A service either calls repositories request by request or runs a unit of work; it never mixes the two.
• Errors are data. Services throw AppError subclasses with an ErrorCode; the API handlers translate them into wire errors.

The package rules shared with the rest of the monorepo are on Architecture and Adapter packages.

Source layout