Repository Pattern

# ADR - Introduce TaskRepository incrementally

## Decision
Introduce TaskRepository for complex/scoped Task persistence queries and straightforward writes. Do not create GenericRepository<T>. Do not force all cross-feature transactions behind repositories yet.

## Why now
TasksService now contains enough persistence-specific query construction that it obscures business intent and complicates unit testing.

## Consequences
- Service unit tests can use a fake repository.
- Prisma query behavior moves into integration-tested adapter code.
- Some direct Prisma orchestration may remain temporarily where transaction correctness would otherwise become less clear.

# TaskFlow Phase 24 - Repository Pattern

This snapshot introduces a focused TaskRepository boundary without converting the entire application into a generic repository architecture.

Default architecture:
- TasksService owns business policy and workflow meaning.
- TaskRepository defines persistence operations the service actually needs.
- PrismaTaskRepository implements those operations with Prisma 7.9.1.
- Cross-feature transaction abstraction is intentionally deferred until repeated pressure justifies it.

# Sources

- NestJS - Custom providers: https://docs.nestjs.com/fundamentals/custom-providers - Interfaces are erased at runtime; custom string/symbol tokens can bind an interface contract to a concrete provider.
- NestJS - Testing: https://docs.nestjs.com/fundamentals/testing - TestingModule can replace/override providers so business services can be tested against doubles.
- Prisma ORM v7 - Unit testing: https://docs.prisma.io/docs/orm/prisma-client/testing/unit-testing - Prisma documents dependency injection and mocking as valid unit-testing approaches.
- Prisma ORM v7 - Best practices: https://www.prisma.io/docs/orm/v7/more/best-practices - Current Prisma guidance separates unit tests with mocks from integration tests against a resettable database.
- Prisma ORM v7 - Transactions: https://docs.prisma.io/docs/orm/v7/prisma-client/queries/transactions - Nested writes, batch transactions, and interactive transactions remain persistence-specific concerns.

import { Injectable } from "@nestjs/common"
import { PrismaService } from "../../prisma/prisma.service"
import type { Prisma } from "../../generated/prisma/client"
import type { PaginatedTasks, TaskListQuery, TaskRepository, CreateTaskRecord, UpdateTaskRecord } from "./task.repository"

@Injectable()
export class PrismaTaskRepository implements TaskRepository {
  constructor(private readonly prisma: PrismaService) {}

  findById(id: string) {
    return this.prisma.task.findUnique({ where: { id } })
  }

  findScopedById(taskId: string, userId: string) {
    return this.prisma.task.findFirst({
      where: {
        id: taskId,
        project: {
          workspace: {
            memberships: { some: { userId } },

import type { TaskPriority, TaskStatus } from "../../generated/prisma/client"

export const TASK_REPOSITORY = Symbol("TASK_REPOSITORY")

export type TaskRecord = {
  id: string
  projectId: string
  assigneeId: string | null
  title: string
  description: string | null
  status: TaskStatus
  priority: TaskPriority
  dueAt: Date | null
  completedAt: Date | null
  createdAt: Date
  updatedAt: Date
}

export type TaskListQuery = {
  projectId?: string

import { Module } from "@nestjs/common"
import { TasksController } from "./tasks.controller"
import { TasksService } from "./tasks.service.phase24"
import { TASK_REPOSITORY } from "./repositories/task.repository"
import { PrismaTaskRepository } from "./repositories/prisma-task.repository"

@Module({
  controllers: [TasksController],
  providers: [
    TasksService,
    {
      provide: TASK_REPOSITORY,
      useClass: PrismaTaskRepository,
    },
  ],
  exports: [TasksService],
})
export class TasksModule {}

import { Inject, Injectable } from "@nestjs/common"
import { TASK_REPOSITORY, type TaskRepository } from "./repositories/task.repository"

@Injectable()
export class TasksService {
  constructor(
    @Inject(TASK_REPOSITORY)
    private readonly tasks: TaskRepository,
  ) {}

  async findOneForUser(taskId: string, userId: string) {
    const task = await this.tasks.findScopedById(taskId, userId)
    if (!task) {
      // Reuse the Phase 13/19 application exception contract.
      throw new Error("Task not found in authorized scope")
    }
    return task
  }

  async listForUser(userId: string, query: Parameters<TaskRepository["listScoped"]>[1]) {

import type { CreateTaskRecord, PaginatedTasks, TaskListQuery, TaskRecord, TaskRepository, UpdateTaskRecord } from "../apps/api/src/tasks/repositories/task.repository"

export class FakeTaskRepository implements TaskRepository {
  readonly items = new Map<string, TaskRecord>()

  async findById(id: string) { return this.items.get(id) ?? null }
  async findScopedById(id: string, _userId: string) { return this.items.get(id) ?? null }

  async listScoped(_userId: string, query: TaskListQuery): Promise<PaginatedTasks> {
    const all = [...this.items.values()]
    const start = (query.page - 1) * query.pageSize
    const data = all.slice(start, start + query.pageSize)
    const totalItems = all.length
    const totalPages = Math.ceil(totalItems / query.pageSize)
    return { data, meta: { page: query.page, pageSize: query.pageSize, totalItems, totalPages, hasPreviousPage: query.page > 1, hasNextPage: query.page < totalPages } }
  }

  async create(input: CreateTaskRecord) {
    const now = new Date()
    const task = { id: crypto.randomUUID(), projectId: input.projectId, assigneeId: null, title: input.title, description: input.description ?? null, status: "TODO" as const, priority: "MEDIUM" as const, dueAt: null, completedAt: null, createdAt: now, updatedAt: now }

# PrismaTaskRepository integration checklist

Use a dedicated resettable PostgreSQL test database.

- Apply the same Prisma migrations used by development.
- Seed two Users, two Workspaces, Memberships, Projects and Tasks.
- listScoped(userA) never returns Workspace B data.
- findScopedById(userA, taskB) returns null.
- status/priority/search filters produce the expected rows.
- page metadata and row query share the same filter.
- stable sort uses id as a tiebreaker.
- nullable assignee and dueAt values map correctly.
- database errors are translated at the appropriate boundary.

import { Test } from "@nestjs/testing"
import { TASK_REPOSITORY } from "../apps/api/src/tasks/repositories/task.repository"
import { TasksService } from "../apps/api/src/tasks/tasks.service.phase24"
import { FakeTaskRepository } from "./fake-task.repository"

describe("TasksService repository boundary", () => {
  it("can replace persistence without starting PostgreSQL", async () => {
    const fake = new FakeTaskRepository()
    const moduleRef = await Test.createTestingModule({
      providers: [
        TasksService,
        { provide: TASK_REPOSITORY, useValue: fake },
      ],
    }).compile()

    const service = moduleRef.get(TasksService)
    expect(service).toBeDefined()
  })
})