Title How are teams organizing Prisma in large codebases with 100+ models?

[Saif0933]

Question

In small projects, it's easy to keep Prisma queries inside services, but in larger applications with dozens of modules and hundreds of queries, how are teams organizing Prisma access?

Are you using repositories, domain services, query builders, or keeping Prisma directly in the service layer?

I'd love to hear real-world patterns from teams running Prisma in production.

[P4ST4S]

In larger Prisma codebases, I would avoid making this a binary choice between "repository everywhere" and "Prisma directly everywhere".

A pattern that has worked well for me is:

1. Keep Prisma Client directly in small feature services when the query is local, simple, and not reused.
2. Extract query modules or repositories only when there is real shared query logic, complex filtering, pagination, authorization scoping, or transaction reuse.
3. Keep business decisions outside the repository layer. The repository should know how to query; the domain or application service should know why.
4. Make transaction boundaries explicit at the service or use-case level, not hidden inside low-level repositories.

For example, instead of one repository per model with thin wrappers like:

userRepository.findById(id)

I would rather keep Prisma direct:

await prisma.user.findUnique({ where: { id } })

But once queries become domain-specific, extraction becomes useful:

export function buildActiveCustomerWhere(input: CustomerFilters): Prisma.CustomerWhereInput {
  return {
    deletedAt: null,
    ...(input.search
      ? {
          OR: [
            { name: { contains: input.search, mode: "insensitive" } },
            { email: { contains: input.search, mode: "insensitive" } },
          ],
        }
      : {}),
  };
}

Then the service can compose it:

const where = buildActiveCustomerWhere(filters);

return prisma.customer.findMany({
  where,
  orderBy: { createdAt: "desc" },
  take: limit,
  skip: offset,
});

For very large apps, I usually split by domain or module rather than by database table:

src/
  billing/
    billing.service.ts
    billing.queries.ts
    billing.mappers.ts
  users/
    users.service.ts
    users.queries.ts
  shared/
    prisma/
      prisma.service.ts

The main thing I would avoid is creating a generic CRUD repository abstraction over Prisma too early. Prisma already gives you a typed query API, so wrapping every method often removes type power without adding much value.

A good rule of thumb:

• Simple one-off query: use Prisma directly in the service.
• Reused filter, include, or order logic: extract query builders.
• Cross-model domain workflow: service or use-case owns orchestration.
• Multi-step write consistency: pass a transaction client explicitly.

Example:

async function createOrder(input: CreateOrderInput) {
  return prisma.$transaction(async (tx) => {
    const customer = await tx.customer.findUniqueOrThrow({
      where: { id: input.customerId },
    });

    const order = await tx.order.create({
      data: {
        customerId: customer.id,
        items: {
          create: input.items,
        },
      },
    });

    return order;
  });
}

So my recommendation would be: start with Prisma in services, extract query builders and domain-specific repositories when duplication or complexity appears, and keep transaction boundaries visible.

Did this resolve it? Feel free to mark as answer if so.

[Saif0933]

Thanks for the detailed response. I think we agree on most of the architectural principles, especially avoiding generic CRUD repositories and keeping transaction boundaries explicit.

The part I'm still trying to understand is how this fits with the direction of Prisma Next.

In Prisma 7, many teams (including ours) rely heavily on composable WhereInput objects and query builders because they can be passed across layers, merged with object spread syntax, and tested independently before execution.

With the newer chain-based API, my concern isn't where the query lives (service vs repository), but whether the same level of composability remains available.

For example, if I have:

const customerFilter = buildActiveCustomerWhere(filters);

can that still remain a first-class pattern in Prisma Next, or is the expectation that composition happens through the query chain itself?

In larger systems, we often build filters incrementally from:

User input
Authorization rules
Tenant scoping
Domain-specific business rules

before the query is finally executed.

I'm curious whether the Prisma team sees plain-object query composition as a long-term supported pattern, or whether query builders/collections are expected to become the primary abstraction going forward.

That's the migration concern I'm trying to understand for larger codebases.

[P4ST4S]

@Saif0933 That is exactly the right migration concern.

I would separate two things:

1. where the final query is executed
2. how the query constraints are built before execution

Even if Prisma moves more toward a chain-style API, I would still want tenant scope, authorization scope, user filters, and domain rules to be composable before the query is executed. In a large codebase, that composition step is too important to bury inside the final query call.

Today, I would keep plain-object composition as the application boundary, but make it disciplined:

import { Prisma } from "@prisma/client";

type CustomerWhere = Prisma.CustomerWhereInput;

function tenantScope(tenantId: string): CustomerWhere {
  return { tenantId };
}

function visibleToUser(user: CurrentUser): CustomerWhere {
  if (user.role === "ADMIN") return {};
  return { ownerId: user.id };
}

function activeCustomerFilter(input: CustomerFilters): CustomerWhere {
  return {
    deletedAt: null,
    ...(input.search
      ? {
          OR: [
            { name: { contains: input.search, mode: "insensitive" } },
            { email: { contains: input.search, mode: "insensitive" } },
          ],
        }
      : {}),
  };
}

function andWhere(...parts: CustomerWhere[]): CustomerWhere {
  const nonEmpty = parts.filter((part) => Object.keys(part).length > 0);

  if (nonEmpty.length === 0) return {};
  if (nonEmpty.length === 1) return nonEmpty[0];

  return { AND: nonEmpty };
}

Then the use case composes constraints explicitly:

const where = andWhere(
  tenantScope(ctx.tenantId),
  visibleToUser(ctx.user),
  activeCustomerFilter(filters),
);

return prisma.customer.findMany({
  where,
  orderBy: { createdAt: "desc" },
  take: limit,
  skip: offset,
});

I prefer this over arbitrary object spreading for complex systems, because object spreading can accidentally overwrite AND, OR, relation filters, or nested conditions. Using explicit AND composition makes the merge semantics obvious.

If Prisma Next eventually provides a stronger chain/query-builder abstraction, I would still keep this layer. The only thing I would change is the adapter at the edge:

const constraints = buildCustomerConstraints(ctx, filters);

// current Prisma Client
prisma.customer.findMany({ where: constraints.where });

// future chain-style API, if that becomes the preferred surface
customerQuery.where(constraints.where);

So my answer would be:

• plain-object query composition is still the safest pattern to use today
• do not scatter raw object spreads everywhere
• centralize filter composition into small typed helpers
• keep authorization and tenant filters as mandatory query fragments
• isolate the final Prisma call so a future query-chain API only changes the adapter layer

The key is not "repository vs service". The key is making query constraints explicit, typed, testable, and composable before execution.

[BrenoRev]

Guys, how are you mapping Prisma query results to DTOs? I'm assuming you're using select rather than include. In my case, i need to create an Class for every repository select pattern ( every query ) and use object mapper to maintain mapping logic out of service classes.

[P4ST4S]

@BrenoRev For large codebases, I would avoid creating one class per Prisma select pattern unless the DTO is part of a stable API boundary.

The pattern I prefer is:

1. keep Prisma select objects close to the query
2. derive the TypeScript result type from the select
3. map to an explicit DTO only at module/API boundaries

Example:

import { Prisma } from "@prisma/client";

const userListSelect = {
  id: true,
  email: true,
  name: true,
  createdAt: true,
  profile: {
    select: {
      avatarUrl: true,
    },
  },
} satisfies Prisma.UserSelect;

type UserListRow = Prisma.UserGetPayload<{
  select: typeof userListSelect;
}>;

type UserListDto = {
  id: string;
  email: string;
  name: string | null;
  avatarUrl: string | null;
  createdAt: string;
};

function toUserListDto(row: UserListRow): UserListDto {
  return {
    id: row.id,
    email: row.email,
    name: row.name,
    avatarUrl: row.profile?.avatarUrl ?? null,
    createdAt: row.createdAt.toISOString(),
  };
}

Then your repository/query function stays simple:

export async function listUsers(): Promise<UserListDto[]> {
  const rows = await prisma.user.findMany({
    select: userListSelect,
    orderBy: { createdAt: "desc" },
  });

  return rows.map(toUserListDto);
}

I would not put mapping logic in service classes, but I also would not introduce a heavy object mapper too early. In most Prisma projects, small pure mapper functions are easier to maintain and easier to type-check.

My rule of thumb:

• internal feature code: Prisma payload type is often enough
• public API response: map to an explicit DTO
• reused projection: extract the select object and mapper together
• many variants of the same entity: name them by use case, not by table, for example UserListDto, UserDetailDto, UserAdminDto

The important part is to let Prisma infer the query result from the actual select, instead of manually duplicating that shape in a class for every query. That keeps the compiler connected to your query.

[BrenoRev]

Thanks.

[ryanzen9]

Hi everyone In complex business scenarios, how do you persist a complex domain object or aggregate root (MVC or DDD)?

Persisting such objects often requires writes across multiple tables, preferably within the same transaction. My current approach is to encapsulate the write logic in a WriteRepository and explicitly pass the transaction context/manager through the call chain.

It works, but it doesn't feel particularly elegant. I'd love to hear how others handle this kind of problem.

[P4ST4S]

@ryanzen9 For DDD-style aggregates with Prisma, I would not try to make Prisma behave like a transparent Unit of Work ORM.

The pattern I prefer is:

1. the application service owns the transaction boundary
2. the aggregate enforces business invariants in memory
3. a domain-specific repository persists the aggregate using Prisma
4. the transaction client is passed explicitly, but hidden behind a small type alias or UnitOfWork helper

For a simple aggregate that can be written in one Prisma call, use nested writes. Prisma already wraps nested writes in a transaction:

await prisma.order.create({
  data: {
    customerId: order.customerId,
    status: order.status,
    items: {
      create: order.items.map((item) => ({
        productId: item.productId,
        quantity: item.quantity,
        unitPrice: item.unitPrice,
      })),
    },
  },
});

For more complex cases where you need reads, decisions, optimistic checks, or multiple writes, I would use an interactive transaction at the use-case level:

import { Prisma, PrismaClient } from "@prisma/client";

type Db = PrismaClient | Prisma.TransactionClient;

class OrderWriteRepository {
  async save(order: OrderAggregate, db: Db) {
    await db.order.update({
      where: { id: order.id },
      data: {
        status: order.status,
        totalAmount: order.totalAmount,
      },
    });

    await db.orderItem.deleteMany({
      where: { orderId: order.id },
    });

    await db.orderItem.createMany({
      data: order.items.map((item) => ({
        orderId: order.id,
        productId: item.productId,
        quantity: item.quantity,
        unitPrice: item.unitPrice,
      })),
    });
  }
}

async function confirmOrder(orderId: string) {
  return prisma.$transaction(async (tx) => {
    const order = await orderRepository.getById(orderId, tx);

    order.confirm();

    await orderWriteRepository.save(order, tx);

    await outboxRepository.add(order.pullDomainEvents(), tx);

    return order.id;
  });
}

That is explicit, but it is explicit in the right place: the use case controls consistency.

If passing tx everywhere feels noisy, I would wrap it one level higher rather than hiding transactions inside repositories:

async function withUnitOfWork<T>(
  fn: (uow: { db: Prisma.TransactionClient }) => Promise<T>,
): Promise<T> {
  return prisma.$transaction((tx) => fn({ db: tx }));
}

Then your use case becomes:

await withUnitOfWork(async ({ db }) => {
  const order = await orderRepository.getById(orderId, db);

  order.confirm();

  await orderWriteRepository.save(order, db);
  await outboxRepository.add(order.pullDomainEvents(), db);
});

The main thing I would avoid is each repository starting its own transaction internally. That makes cross-aggregate workflows hard to reason about and can accidentally split one business invariant across multiple database transactions.

My rule of thumb:

• one aggregate, simple graph: nested write
• one aggregate, complex persistence: aggregate-specific repository plus transaction client
• multiple aggregates in one business operation: application service owns prisma.$transaction
• side effects after commit: write to an outbox table inside the same transaction, then process asynchronously
• if a workflow needs many aggregates often, revisit the aggregate boundary

So your current approach is not wrong. Passing the transaction context explicitly is usually the correct tradeoff with Prisma. The improvement is mostly to make it ergonomic with a small UnitOfWork abstraction, not to hide the transaction boundary.

[ryanzen9]

Thank you very much for your response.

The example you provided is very clear and closely matches the structure of my code. As you mentioned, explicitly passing the transaction context in Prisma seems to be the approach encouraged by the framework, and it may also be one of the characteristics that distinguishes it from more traditional ORMs.

Your code serves as an excellent reference for me. Thank you again for your reply.

[logusivam]

This is a great architectural question, and there's no single "correct" answer — the right pattern depends on your team size, domain complexity, and how much abstraction overhead you're willing to maintain. Here's what teams actually use in production, with honest trade-offs for each.

---

Pattern 1 — Prisma directly in the service layer (flat, no abstraction)

The simplest approach. Services call prisma.model.findMany() directly with no intermediate layer.

// services/order.service.ts
export class OrderService {
  constructor(private readonly prisma: PrismaClient) {}

  async getOrdersForUser(userId: string, status?: OrderStatus) {
    return this.prisma.order.findMany({
      where: {
        userId,
        ...(status ? { status } : {}),
      },
      include: { items: true },
      orderBy: { createdAt: 'desc' },
    });
  }
}

When this works:

• Small to medium projects (up to ~20 modules)
• Teams that want to move fast without boilerplate
• Apps where queries don't repeat across services

When it breaks down:

• The same query logic gets duplicated across multiple services
• Business rules encoded in where clauses leak everywhere
• Testing requires mocking PrismaClient directly, which is verbose

---

Pattern 2 — Repository pattern (domain-scoped data access layer)

A repository class per domain model encapsulates all queries for that entity. Services depend on the repository interface, not PrismaClient directly.

// repositories/order.repository.ts
export interface IOrderRepository {
  findByUser(userId: string, filters?: OrderFilters): Promise<Order[]>;
  findById(id: string): Promise<Order | null>;
  create(data: CreateOrderInput): Promise<Order>;
  updateStatus(id: string, status: OrderStatus): Promise<Order>;
}

export class PrismaOrderRepository implements IOrderRepository {
  constructor(private readonly prisma: PrismaClient) {}

  async findByUser(userId: string, filters?: OrderFilters) {
    return this.prisma.order.findMany({
      where: {
        userId,
        ...(filters?.status ? { status: filters.status } : {}),
        ...(filters?.from ? { createdAt: { gte: filters.from } } : {}),
      },
      include: { items: true },
      orderBy: { createdAt: 'desc' },
    });
  }

  async findById(id: string) {
    return this.prisma.order.findUnique({
      where: { id },
      include: { items: { include: { product: true } } },
    });
  }
}

// services/order.service.ts
export class OrderService {
  constructor(private readonly orderRepo: IOrderRepository) {}

  async getUserOrders(userId: string, filters?: OrderFilters) {
    return this.orderRepo.findByUser(userId, filters);
  }
}

When this works:

• Medium to large projects with clear domain boundaries
• Teams that unit-test services with mock repositories
• When you might swap the data layer (e.g., testing with in-memory implementations)

When it breaks down:

• Adds a layer of boilerplate that mirrors Prisma's already-clean API
• Repository interfaces can become leaky abstractions that expose Prisma-specific concerns anyway
• Can create unnecessary indirection when the repository just proxies Prisma 1:1

---

Pattern 3 — Composable query builders / filter functions

Instead of full repository classes, extract reusable where, include, and orderBy fragments as plain functions. Services compose these inline.

// queries/order.queries.ts
export const orderFilters = {
  forUser: (userId: string): Prisma.OrderWhereInput => ({
    userId,
  }),

  withStatus: (status: OrderStatus): Prisma.OrderWhereInput => ({
    status,
  }),

  active: (): Prisma.OrderWhereInput => ({
    status: { notIn: ['CANCELLED', 'REFUNDED'] },
  }),

  placedAfter: (date: Date): Prisma.OrderWhereInput => ({
    createdAt: { gte: date },
  }),
};

export const orderIncludes = {
  withItems: (): Prisma.OrderInclude => ({
    items: { include: { product: true } },
  }),
};

// services/order.service.ts
export class OrderService {
  constructor(private readonly prisma: PrismaClient) {}

  async getActiveOrdersForUser(userId: string) {
    return this.prisma.order.findMany({
      where: {
        ...orderFilters.forUser(userId),
        ...orderFilters.active(),
      },
      include: orderIncludes.withItems(),
      orderBy: { createdAt: 'desc' },
    });
  }
}

When this works:

• Large projects with many shared filter combinations
• Teams that want reuse without the overhead of full repository classes
• When query composition (spreading where objects) is a common pattern across services
• Great for domain logic that determines query structure dynamically (search + filter UIs)

When it breaks down:

• Doesn't help with testing (still need to mock PrismaClient)
• Can accumulate into a large, hard-to-navigate query library if not organized well

---

Pattern 4 — Domain service layer with explicit read/write separation (CQRS-lite)

Separate read concerns from write concerns explicitly. Read operations use thin query functions; write operations go through domain services that enforce business rules.

// reads/order.reads.ts — thin, no business logic
export const getOrderWithItems = (prisma: PrismaClient, orderId: string) =>
  prisma.order.findUnique({
    where: { id: orderId },
    include: { items: { include: { product: true } } },
  });

export const getOrdersByUser = (
  prisma: PrismaClient,
  userId: string,
  filters: OrderFilters
) =>
  prisma.order.findMany({
    where: { userId, ...buildOrderWhere(filters) },
    orderBy: { createdAt: 'desc' },
  });

// domain/order.domain.ts — business rules live here
export class OrderDomain {
  constructor(private readonly prisma: PrismaClient) {}

  async cancelOrder(orderId: string, requestedBy: string) {
    const order = await getOrderWithItems(this.prisma, orderId);

    if (!order) throw new NotFoundError('Order not found');
    if (order.userId !== requestedBy) throw new ForbiddenError();
    if (order.status === 'SHIPPED') throw new BusinessRuleError('Cannot cancel a shipped order');

    return this.prisma.order.update({
      where: { id: orderId },
      data: { status: 'CANCELLED', cancelledAt: new Date() },
    });
  }
}

When this works:

• Large teams where business rules need to be clearly separated from data access
• Applications with complex domain logic that shouldn't live in a query layer
• Teams already familiar with CQRS concepts

When it breaks down:

• Higher conceptual overhead — new developers need to know which layer to look in
• Overkill for CRUD-heavy applications with minimal domain logic

---

What teams actually do in production — the honest summary

Based on how large Prisma production codebases are typically structured:

Team/App size	Most common pattern
Small (1–5 devs, <20 modules)	Prisma directly in services
Medium (5–15 devs, 20–50 modules)	Composable query builders + Prisma in services
Large (15+ devs, 50+ modules)	Repository pattern OR CQRS-lite with domain services
Enterprise with DDD	Full repository pattern with interface injection

The most pragmatic pattern for most production teams hitting scale is a hybrid: Prisma stays in the service layer for simple queries, composable query builder functions handle shared filter logic, and repository classes are introduced only for domain models complex enough to warrant the abstraction — not applied uniformly across all models.

---

Practical recommendation for a large, multi-module codebase

Start with this structure and add abstraction only where pain appears:

src/
  modules/
    orders/
      orders.service.ts        ← business logic, calls prisma or repo
      orders.queries.ts        ← reusable where/include fragments
      orders.repository.ts     ← only if testing isolation is needed
      orders.controller.ts
  prisma/
    client.ts                  ← singleton PrismaClient export

// prisma/client.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
  });

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

The singleton pattern above is important at scale — it prevents connection pool exhaustion from multiple PrismaClient instances being instantiated across modules (a common production issue).

---

On testing — the practical approach at scale

Regardless of which pattern you choose, the two most viable testing strategies for Prisma at scale are:

Option A — Test against a real database (recommended)
Use a separate test database with prisma migrate reset in your test setup. This gives you confidence that your actual queries work, not just your mocks. Tools like vitest with a per-test transaction rollback keep this fast.

Option B — Mock at the service boundary
Use jest-mock-extended to mock PrismaClient if you want pure unit tests. This works best when services are thin and repositories encapsulate the Prisma-specific logic — which is one of the main practical arguments for the repository pattern even if you don't strictly need the abstraction.

Hope this helps — if it answers your question, would you mind clicking "Mark as answer" so others searching for the same thing can find it quickly?

[JosephHampton]

A few patterns that hold up past 100 models, roughly from least to most structure:

1. One PrismaClient, but keep it behind boundaries. Single instantiated client (a singleton), but don't import it straight into route handlers. Everything goes through a layer. The real question isn't "repository vs service", it's "is Prisma an implementation detail behind a boundary, or is it your domain?"

2. Organise by feature or domain, not one big db/ folder. Instead of services/userService.ts plus services/orderService.ts all reaching into one giant client, colocate by domain:

src/modules/
  billing/    billing.repo.ts, billing.service.ts, billing.types.ts
  catalog/    catalog.repo.ts, catalog.service.ts
  identity/   ...

Each module owns its own queries, and cross module access goes through the other module's service rather than reaching into its tables directly. That's the thing that stops 100+ models turning into a big ball of mud.

3. Repositories for the gnarly queries, Prisma in the service for plain CRUD. Thin CRUD can just call Prisma in the service. Anything with a complex include / where / transaction gets a named repository method (orderRepo.findWithLineItems(id)) so the query lives in one testable spot and callers aren't copy pasting the same 40 line include tree everywhere.

4. Split the schema file. Prisma supports multi file schemas (prisma/schema/*.prisma). Split by domain so people aren't fighting merge conflicts in one 4000 line file.

5. Derive your types, don't hand write DTOs. Prisma.UserGetPayload<{ include: ... }> and Prisma.validator let you pull types straight from your query shapes instead of maintaining parallel interfaces that drift out of sync.

One thing I'd avoid is a single generic Repository<T> over every model. It fights Prisma's type inference and you lose the exact thing Prisma is best at. Prefer explicit named methods per aggregate.

Short version: one client, organise by business domain, named repositories for the complex queries, multi file schema, and derive your types from Prisma.

If this was useful it'd be great if you could mark it as the answer.

[jaendmzgb1645-ux]

کد فلیتر روبیکا

[jaendmzgb1645-ux]

کد فلیتر روبیکا فوری

[VIJAYAPANDIANT]

I generally use a hybrid approach that keeps the codebase simple while allowing it to scale.

• For straightforward CRUD operations, I use Prisma directly in the service layer.
• When filters, pagination, authorization, or tenant-scoped queries are reused across multiple features, I extract them into dedicated query builder functions.
• I organize modules by business domain (users, orders, billing, etc.) instead of by database tables, which makes ownership and maintenance much clearer.
• I keep transaction boundaries in the application/service layer using prisma.$transaction() rather than hiding them inside repositories.

This approach has worked well because it avoids unnecessary abstractions early on while still providing reusable, testable query logic as the project grows.

I'm also curious whether teams using Prisma 7 have adjusted this pattern or are still following a similar architecture.

[VJT67]

I usually keep query builders close to the feature they belong to.

For example:

src/
modules/
users/
users.service.ts
users.queries.ts
users.controller.ts
orders/
orders.service.ts
orders.queries.ts

This keeps reusable filters and query logic within the same domain instead of placing everything in a shared folder. It also makes the code easier to maintain as the application grows.

[Nithwin]

This is something I've wrestled with too, and the honest answer is there's no single correct pattern — but there are some clear anti-patterns that hurt at 100+ models.

The core issue with Prisma at scale

The instinct to reach for "repository pattern" comes from a world where the ORM was clunky and you wanted to hide it. Prisma's type-safe query API is actually pretty good, so wrapping every model in a thin repository that just proxies findMany, create, etc., removes type power without adding much. You end up maintaining two APIs.

The pattern that actually holds up in large codebases is a pragmatic tiered approach:

Tier 1 — Prisma directly in the service (the default)

For queries that are local to one service and not reused, just call Prisma:

// no ceremony needed
const user = await prisma.user.findUniqueOrThrow({ where: { id } });

Tier 2 — Composable query builders for shared logic

When the same filter/include logic appears in multiple places, extract it as a typed function rather than a class:

// src/modules/orders/orders.queries.ts
import { Prisma } from '@prisma/client';

export function activeOrdersWhere(userId: string): Prisma.OrderWhereInput {
  return {
    userId,
    status: { notIn: ['CANCELLED', 'REFUNDED'] },
    deletedAt: null,
  };
}

export const withOrderItems = (): Prisma.OrderInclude => ({
  items: { include: { product: true } },
});

Then services compose:

const orders = await prisma.order.findMany({
  where: activeOrdersWhere(userId),
  include: withOrderItems(),
});

Tier 3 — Repository/module for complex domain logic

Repository classes only earn their place when you have complex multi-step queries, authorization scoping, or queries you need to unit-test in isolation. The bar should be real complexity, not just "every model gets a repo".

Organize by feature, not by model

This is probably the most important structural decision. At 100+ models, a flat repositories/ folder becomes a navigation nightmare. Organize by domain module instead:

src/
  modules/
    billing/
      billing.service.ts      # business logic
      billing.queries.ts      # reusable where/include fragments
      billing.repository.ts   # only if complex enough to warrant it
      billing.types.ts
    catalog/
      catalog.service.ts
      catalog.queries.ts
    identity/
      ...
  db/
    client.ts                 # singleton PrismaClient — one instance total

Cross-module data access goes through the other module's service, not direct table access. That boundary stops things from becoming a big ball of mud as models accumulate.

On transactions

Transaction boundaries belong at the service/use-case layer, not inside repositories. The pattern that keeps things clear:

async function createOrder(input: CreateOrderInput) {
  return prisma.$transaction(async (tx) => {
    const customer = await tx.customer.findUniqueOrThrow({ where: { id: input.customerId } });
    const order = await tx.order.create({
      data: { customerId: customer.id, items: { create: input.items } },
    });
    return order;
  });
}

If passing tx around feels noisy, a small withUnitOfWork wrapper at the use-case level is cleaner than hiding transactions inside repository methods.

Multi-file schema

If you haven't already, split the schema by domain too. Prisma supports multi-file schemas natively — one schema.prisma for datasource/generator, then domain-specific files:

prisma/
  schema/
    schema.prisma   # datasource + generator only
    identity.prisma
    billing.prisma
    orders.prisma
  migrations/       # single history

This directly maps to your module structure and stops merge conflicts in a 4000-line single file.

The rule of thumb I'd apply

• Simple query used once → Prisma in service
• Filter/include logic used in 2+ places → extract to queries.ts
• Complex domain workflow with tests → repository class
• Everything → organize by domain module, not by abstraction type

[Rene-Kuhm]

Addressing the Prisma 7 concern specifically — I just did this migration in a production NestJS codebase and the architecture question shifts meaningfully.

The $use() → $extends() migration changes the pattern

In Prisma 7, $use() middleware was removed. The replacement is $extends(), but it returns a new client instance rather than mutating the existing one. In NestJS, this breaks class PrismaService extends PrismaClient unless you bridge it:

typescript
@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
constructor() {
super({ adapter, log: ['error'] });

// $extends() returns a new client — bridge it back to `this`
const extended = (this as any).$extends({
  query: {
    $allModels: {
      async $allOperations({ model, operation, args, query }) {
        // middleware logic: tenant scoping, slow query logging, etc.
        const start = Date.now();
        const result = await query(args);
        const duration = Date.now() - start;
        if (duration > SLOW_QUERY_THRESHOLD_MS) {
          logger.warn({ model, operation, duration }, 'Slow query');
        }
        return result;
      }
    }
  }
});

Object.assign(this, extended); // preserve existing call sites

}
}

This matters for large codebases because all 9+ services that call prisma.invoice.findMany() keep working without changes — only PrismaService changes.

On composable WhereInput objects in Prisma 7

Plain-object composition still works fine — Prisma.InvoiceWhereInput types are stable. The $extends() API is orthogonal to query building. You can still do:

typescript
const where: Prisma.InvoiceWhereInput = {
...tenantScope(merchantId),
...statusFilter(filters.status),
};
await prisma.invoice.findMany({ where });

The composable filter pattern is not going away with Prisma Next's chain API — the where object you build is still the input to whatever surface executes it.

The pattern that scales at 100+ models with Prisma 7:

PrismaService (singleton, $extends() bridge for cross-cutting concerns)
*.queries.ts per domain (typed WhereInput builders, reusable include fragments)
Repository classes only for complex multi-step workflows that need testing isolation
Multi-file schema split by domain (invoice.prisma, merchant.prisma, etc.)
Transaction boundaries at the service/use-case layer, tx passed explicitly