Groups

The groups module models a class: a named set of students that meets on a schedule and receives sessions. The weekly flag and the start and end dates drive the expected occurrences on the calendar. The teacher app and the API consume it; the sessions module reads groups through the same read port to compute occurrences.

Import from @workspace/training/domain/groups and @workspace/training/application/groups.

Domain

Group

defaultSessionTime is a wall-clock time of day (HH:mm or HH:mm:ss) used as the default for new sessions, null when the group has no recurring time. owner is the Owner projection of the teacher account. studentCount, sessionCount, nextSession and nextExpectedDate are computed on read: the withDetails projection fills the two counts, the entity projection leaves them at zero.

SessionPreview

The lightweight session shown on a group card.

The module has no constants, guards or pure functions. The recurrence arithmetic lives in sessions and takes a RecurringGroup projection of Group.

Application

GroupsService

createGroupsService(deps: GroupsServiceDeps): GroupsService, where GroupsServiceDeps is { groups: GroupsRepository; groupsRead: GroupsReadRepository; groupStudents: GroupStudentsRepository; studentsRead: StudentsReadRepository; entitlements: EntitlementsGate }.

The ServiceContext comes last on every method. The two list methods and create use ctx.userId. The id-scoped methods check ownership first: they count the caller's group (and, for addStudent, the caller's student), throw AccessDeniedError when the caller has no such row, whether it belongs to another account or does not exist, so the answer does not reveal which, and only then read or write it. Each method composes a query object, a criteria or a projection and calls one primitive of the ports below.

export function listGroupsForCards(
  deps: GroupsServiceDeps,
  ctx: ServiceContext
): Promise<GroupWithDetails[]> {
  const groups = createGroupsService(deps);
  return groups.listWithDetails(ctx); // archived included; filter client-side
}

export function createWeeklyGroup(
  deps: GroupsServiceDeps,
  ctx: ServiceContext
): Promise<Group> {
  const groups = createGroupsService(deps);
  return groups.create(
    {
      name: "Monday beginners",
      startDate: "2026-09-07",
      isWeekly: true,
      defaultSessionTime: "18:30",
      color: "#1d4ed8",
    },
    ctx
  );
}

export async function archiveGroup(
  deps: GroupsServiceDeps,
  groupId: string,
  ctx: ServiceContext
): Promise<Group | null> {
  const groups = createGroupsService(deps);
  try {
    return await groups.update(groupId, { isArchived: true }, ctx);
  } catch (error) {
    if (isAppError(error) && error.code === "GROUP_NOT_FOUND") {
      return null;
    }
    throw error;
  }
}

export async function updateRoster(
  deps: GroupsServiceDeps,
  groupId: string,
  ctx: ServiceContext
): Promise<void> {
  const groups = createGroupsService(deps);
  await groups.addStudent(groupId, 42, ctx); // a link on the junction
  await groups.removeStudent(groupId, 42, ctx);
}

DTOs

When id is provided the server uses it as the primary key (client-generated UUID); otherwise the database generates one.

GroupStudentsDTO is the wire shape for the roster endpoints; the service takes the studentIds array directly.

Query objects

The generics are described on Queries. The group family binds them as follows.

GroupQuery (read side), over QueryParams<GroupWhere, GroupSort>.

GroupCriteria (write side and aggregates): byId, byIds, byOwner, where and .and(where). Refuses an empty where.

GroupWhere: id and ownerId, each an Equality<string>. ownerId maps to the owning account.

GroupProjections

GroupWithDetails is Group & { studentCount: number; sessionCount: number }. Both counts already exist on Group, so the type adds nothing structurally; it names the projection that fills them.

GroupAggregations: count(criteria?). GroupSort: { column: "name" \| "createdAt"; desc: boolean }, whitelisted by GROUP_SORT_COLUMNS. GroupPatch: the mutable columns of UpdateGroupDTO.

// Inside a service: the projection drives the row type, no annotation needed.
export function ownedGroupsWithCounts(
  groupsRead: GroupsReadRepository,
  ownerId: string
): Promise<GroupWithDetails[]> {
  return groupsRead.findMany(
    GroupQuery.empty().byOwner(ownerId),
    GroupProjections.withDetails()
  );
}

Ports

GroupsReadRepository is ReadRepository<GroupQuery>: getById(id, projection), findMany(query, projection), findManyPaginated(query, projection), aggregate(aggregation). getById throws NotFoundError(GROUP_NOT_FOUND) when no row matches. The sessions service depends on this port to compute occurrences.

GroupsRepository is WriteRepository<GroupCriteria, GroupPatch, PersistableGroupWrite> plus writeOne(input: PersistableGroupWrite) => Promise<{ groupId: string }>. update, updateMany and delete report the affected ids.

The group students junction

The link between a group and its students is its own repository, as Junction tables prescribes. The students module reads a group's roster through it.

GroupStudentsRepository

GroupStudentsQuery.empty() takes .byGroup(id), .byGroups(ids), .byStudent(id) and .byStudents(ids). GroupStudentsCriteria has byGroup, byStudent, where and .and(where). GroupStudentsWhere is { groupId?: Equality<string>; studentId?: Equality<number> }.

Errors

Test data: makeGroup and makeSessionPreview in Factories. In-memory fakes in Testing: createFakeGroupsRepositories and createFakeGroupStudentsRepository.

export function groupFixture(faker: Faker): Group {
  return makeGroup(faker, { isWeekly: true, isArchived: false });
}