The five-file module pattern

A domain module lives in apps/core-api/src/modules/<name>/ and is built from five files. Dependencies point one way:

routes  ->  controller  ->  service  ->  repository  ->  prisma
                 |
               schema (Zod)

File	Factory	Owns	Must not
`<name>.routes.ts`	`<name>Router(ctx)`	Wiring from `AppContext`, route table, role guards	Hold logic
`<name>.controller.ts`	`create<Name>Controller(service)`	Zod parsing, reading the principal, shaping the response	Touch Prisma
`<name>.service.ts`	`create<Name>Service(repo, ...)`	Business rules, throwing `AppError`	Touch `req` or `res`
`<name>.repository.ts`	`create<Name>Repository(prisma)`	Prisma queries, scoped by `studioId`	Hold rules
`<name>.schema.ts`	exported Zod schemas	Input contract and inferred types

Everything is a factory function that returns an object of functions. There are no classes and no decorators. The type of each layer is derived with ReturnType:

export type ProductsService = ReturnType<typeof createProductsService>;

Worked example: products

modules/products/ is a small, complete module. It manages the plans a studio sells (the Product model).

Schema

products.schema.ts holds one schema per input and exports the inferred type next to it.

export const productListQuery = z.object({
  active: z.coerce.boolean().optional(),
  search: z.string().optional(),
  page: z.coerce.number().int().positive().default(1),
  pageSize: z.coerce.number().int().positive().max(500).default(20),
});
export type ProductListQuery = z.infer<typeof productListQuery>;

export const createProductBody = z.object({
  name: z.string().min(1),
  displayName: z.string().nullable().optional(),
  tag: z.string().max(40).nullable().optional(),
  priceAgorot: z.number().int().nonnegative().nullable().default(null),
  durationValue: z.number().int().positive().nullable().default(null),
  durationUnit: durationUnit.default('MONTHS'),
  onboardingFormId: z.string().min(1).nullable().optional(),
  updateFormId: z.string().min(1).nullable().optional(),
  active: z.boolean().default(true),
});

export const idParam = z.object({ id: z.string().min(1) });

Two details are worth copying:

Query strings use z.coerce because Express gives strings. Bodies do not coerce.
null has a meaning. A null price means the coach decides per trainee. It is not 0 (a free plan) and not absent, so that clearing a value on an existing plan can be expressed. The comment in the file explains this.

Repository

products.repository.ts is the only file in the module that imports Prisma types. Every read takes studioId.

export function createProductsRepository(prisma: PrismaClient) {
  const byId = async (studioId: string, id: string) => {
    const product = await prisma.product.findFirst({ where: { id, studioId }, include });
    return product ? shape(product) : null;
  };

  const update = (id: string, input: UpdateProductBody) =>
    prisma.product
      .update({ where: { id }, data: input as Prisma.ProductUncheckedUpdateInput, include })
      .then(shape);

  // listByStudio, listLiveSubscriptions, formInStudio, create, remove
}

byId uses findFirst with { id, studioId }, not findUnique with { id }. That is the tenancy check. update and remove take only id, and rely on the service having called get(studioId, id) first. The include object is declared once with satisfies Prisma.ProductInclude, and a shape function turns _count.clients into clientCount. Response shaping that depends on the query belongs here.

Service

products.service.ts receives the repository and, optionally, another module’s service.

export function createProductsService(
  repo: ProductsRepository,
  subscriptions?: ClientSubscriptionsService,
) {
  const get = async (studioId: string, id: string) => {
    const product = await repo.byId(studioId, id);
    if (!product) throw new AppError(ErrorCode.NOT_FOUND, 'product not found');
    return product;
  };

  const update = async (studioId: string, id: string, input: UpdateProductBody) => {
    await get(studioId, id);
    await assertForms(studioId, input);
    return repo.update(id, input);
  };
  // ...
}

Rules the service enforces:

studioId is always the first argument.
An onboarding or update form linked to a plan must exist in the same studio (repo.formInStudio) and have the right type (assertAutomaticFormType).
assignBulk loops over clients, catches AppError per client and reports { clientId, assigned, reason }, where reason is the error code. Any other error is rethrown. One trainee failing a rule does not fail the batch.

Controller

products.controller.ts is thin on purpose. Each handler parses, calls the service and responds.

function studioIdOf(req: AppRequest): string {
  const id = req.auth?.studioId;
  if (!id) throw new AppError(ErrorCode.UNAUTHORIZED, 'authentication required');
  return id;
}

const list = async (req: Request, res: Response) => {
  const query = productListQuery.parse(req.query);
  const { items, total } = await service.list(studioIdOf(req), query);
  ok(res, req, { items, total, page: query.page, pageSize: query.pageSize });
};

const remove = async (req: Request, res: Response) => {
  const { id } = idParam.parse(req.params);
  await service.remove(studioIdOf(req), id);
  noContent(res);
};

studioIdOf is redefined at the top of each controller. It is the one place the studio is read, and it comes from req.auth, never from the body or the path.

Routes

products.routes.ts wires the layers and declares the route table.

export function productsRouter(ctx: AppContext): Router {
  const repository = createProductsRepository(ctx.prisma);
  const subscriptionsService = createClientSubscriptionsService(
    createClientSubscriptionsRepository(ctx.prisma),
    createClientsRepository(ctx.prisma).byId,
    createTraineeNotifier({ prisma: ctx.prisma, logger: ctx.logger }),
    subscriptionAssignedHook(ctx),
  );
  const service = createProductsService(repository, subscriptionsService);
  const controller = createProductsController(service);

  const router = Router();
  router.get('/', controller.list);
  router.get('/active-by-client', controller.listActiveByClient);
  router.post('/', requireRole(StudioRole.OWNER, StudioRole.HEAD_COACH), controller.create);
  router.get('/:id', controller.get);
  router.get('/:id/assignments', controller.assignments);
  router.post('/:id/assign-bulk', requireRole(StudioRole.OWNER, StudioRole.HEAD_COACH), controller.assignBulk);
  router.patch('/:id', requireRole(StudioRole.OWNER, StudioRole.HEAD_COACH), controller.update);
  router.delete('/:id', requireRole(StudioRole.OWNER, StudioRole.HEAD_COACH), controller.remove);
  return router;
}

Note the order: /active-by-client is registered before /:id, otherwise Express would treat it as an id.

Mount

modules/index.ts mounts it on the web lane:

router.use('/web/products', web, productsRouter(ctx));

Variations you will meet

The five-file split is the default, not a law the code follows everywhere. Read the module before assuming.

Variation	Example	What it means
Fewer files	`program-folders` has `routes.ts` and `schema.ts` only. The service lives inside the routes file and calls Prisma directly. `public` and `mcp` are a single routes file.	Fine for a handful of trivial CRUD routes. Still scopes by `studioId`.
No repository	`assistant`, `plan-import`, `forms-ai` take `prisma` in the service.	These are orchestration services around an LLM call.
Extra files	`clients` has `clients.date-filters.ts`, `clients.plan-filters.ts` and more. `trainee` has over twenty helper files. `billing` has `billing.limits.ts`, `billing.seats.ts`, `billing.plan.ts`, `billing.wiring.ts`.	Pure helpers are split out by topic so they can be unit tested.
Several routers per module	`foods` exports `foodsRouter` and `traineeFoodsRouter`. `notification-configs` exports five routers.	One module serving more than one lane. Each router has its own guard.
A `*.wiring.ts` file	`forms.wiring.ts`, `form-sign.wiring.ts`, `billing.wiring.ts`	The dependency graph got big enough to share between routers.
A module with no routes	`tasks`, `update-forms`, `client-subscriptions`, `automation-hooks`, `demo-activity`	Logic used by workers or by other modules’ routers.

Cross module dependencies

When a service needs another module, it receives that module’s service or a single function as a constructor argument. It does not import the other module’s repository to run its own queries. Side effects that cross modules are passed as hooks. createProgramsService takes a PlanActivatedHook, createFormsService takes an onFormSent hook, createClientSubscriptionsService takes a subscriptionAssignedHook(ctx). The router that owns the wiring decides what the hook does. This keeps services testable with plain fakes and stops import cycles. A notifier is a dependency like any other. createTraineeNotifier({ prisma, logger }) returns { send, notify }. The automation lane passes a silent implementation of the same shape when a request asks for no notification.

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

The five-file module pattern

Worked example: products

Schema

Repository

Service

Controller

Routes

Mount

Variations you will meet

Cross module dependencies

​Worked example: products

​Schema

​Repository

​Service

​Controller

​Routes

​Mount

​Variations you will meet

​Cross module dependencies

Worked example: products

Schema

Repository

Service

Controller

Routes

Mount

Variations you will meet

Cross module dependencies