Hands-On Lab and Phase Exit Volume 07 - Advanced Application Architecture | Phase 24
Lab 1 - Identify pressure Open the current TasksService. Mark each line as HTTP concern, business policy, authorization policy, persistence query, persistence mapping, or transaction concern. Only the persistence categories are candidates for TaskRepository.
Lab 2 - Extract listScoped • Define TaskRepository.listScoped().
• Move Prisma where, sorting, skip/take, and count logic into PrismaTaskRepository.
• Keep filter semantics and authorization policy clear.
• Verify the API response does not change.
Lab 3 - Replace the provider in a unit test • Create FakeTaskRepository.
• Use TASK_REPOSITORY with useValue.
• Test one valid status transition.
• Test one invalid transition.
• Confirm no database is required.
Lab 4 - Integration verification • Use a dedicated test PostgreSQL database.
• Apply migrations.
• Create two Workspaces and memberships.
• Verify a scoped repository query never returns the other Workspace Task.
• Verify pagination metadata matches the filtered rows.
Engineer challenge Design how you would support a cross-repository transaction involving Task assignment, Membership validation, and an AuditLog write. Compare: direct Prisma orchestration, a UnitOfWork/transaction context, or a purpose-built persistence operation. Do not implement the most abstract option automatically; justify the cost.
Phase exit checklist • I can explain why Prisma does not automatically require a repository wrapper.
• I can design a contract from service needs rather than ORM methods.
• I can bind an interface-shaped dependency with a NestJS Symbol token.
• I can test business logic with a fake repository.
• I know why repository integration tests still need PostgreSQL.
• I can identify the generic-repository trap.
• I can protect transaction correctness even when the abstraction is imperfect.
Sources used in this phase Source Use in this phase
NestJS - Custom providers Interfaces are erased at runtime; custom string/symbol https://docs.nestjs.com/fundamentals/custom-pr tokens can bind an interface contract to a concrete provider. oviders
NestJS - Testing TestingModule can replace/override providers so business https://docs.nestjs.com/fundamentals/testing services can be tested against doubles.
Prisma ORM v7 - Unit testing Prisma documents dependency injection and mocking as https://docs.prisma.io/docs/orm/prisma-client/tes valid unit-testing approaches. ting/unit-testing
Prisma ORM v7 - Best practices Current Prisma guidance separates unit tests with mocks https://www.prisma.io/docs/orm/v7/more/best-pr from integration tests against a resettable database. actices
Prisma ORM v7 - Transactions Nested writes, batch transactions, and interactive https://docs.prisma.io/docs/orm/v7/prisma-client/ transactions remain persistence-specific concerns. queries/transactions
Hands On Lab and Phase Exit matters because it changes a real boundary in TaskFlow. The goal is to understand the inputs, owner, observable output, and failure modes before adding more abstraction.
Restate the goal of “Hands On Lab and Phase Exit” as one observable behavior. Write the success signal before touching code.
Trace the boundary map: service intent → repository contract → adapter → Prisma/Postgres → domain result. Mark the one boundary this lesson changes.
Inspect the current repository state and record the exact files, route, table, or runtime involved. Avoid creating an abstraction before you can name the existing owner.
Implement the smallest vertical slice. Add one coherent change, run the narrowest verification command, and read the output before continuing.
Connect the slice to TaskFlow’s phase artifact: One TaskFlow aggregate/use case refactored behind a purposeful repository interface with real database integration tests.. Verify behavior from the outside as a user or API client would.
Create one controlled failure that is safe to reproduce. Predict the symptom first, capture evidence, locate the earliest broken boundary, then fix only that cause.
Close the reference and rebuild or explain the core change from memory. Record what you would monitor or test before trusting the same change in production.
export interface TaskRepository {
findById(id: string): Promise<Task | null>;
listForWorkspace(input: TaskListQuery): Promise<TaskPage>;
save(task: Task): Promise<void>;
}Do not copy this as a finished answer. Predict what each boundary does, type the smallest useful slice, run it, then compare the result with your prediction.
Return to the nearest observable boundary: input, network, process log, database, or rendered UI. Compare actual evidence with the predicted path.
Change one variable at a time and reproduce the original failure after the fix; otherwise you have correlation, not diagnosis.
Without copying the final source, create a second small scenario that applies “Hands On Lab and Phase Exit” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Integration-test the real repository against PostgreSQL so fake and implementation do not drift.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.Mapping everything into duplicate types without a domain need
Predict the symptom before causing the failure. Then locate the earliest boundary where reality diverges from expectation.Why does this responsibility live here, what input does it trust, what output proves success, and what would go wrong if another layer owned it?
If your explanation is vague, repeat the boundary trace before moving on.Close the reference. Reproduce the core idea from memory or explain the exact request/data flow aloud. Then check your diff or notes for accidental shortcuts that bypass validation, authorization, error handling, or verification earned in earlier phases.