Hands-On Lab & Phase Exit Workflow rules, membership invariant, transaction reasoning, exercises, and oral exam
Phase 14 - Service & Business Logic Architecture Volume 04 - Professional Backend
v
v
v
Phase 14 turns CRUD-oriented service methods into explicit application rules and workflows while keeping infrastructure simple.
Hands-on lab This lab proves that TaskFlow now protects business state, not only request shape.
Lab A - Status workflow • Implement ALLOWED_STATUS_TRANSITIONS in TasksService.
• Reject a transition that is not in the policy.
• Set completedAt when moving into DONE.
• Clear completedAt when reopening DONE.
• Verify the persisted row after each operation.
Lab B - Workspace assignment invariant • Add assigneeId to write DTOs as optional/nullable UUID.
• Load the Task Project workspace context.
• Verify Membership(workspaceId,userId) exists before assignment.
• Return ASSIGNEE_NOT_WORKSPACE_MEMBER for a syntactically valid non-member.
• Verify unassigning with null succeeds.
Lab C - Transaction reasoning • Implement the explicit /tasks/:id/assignee workflow from the snapshot.
• Use tx for every Prisma query inside the interactive transaction.
• Explain why update-title does not need the same extra transaction.
• Identify one future enterprise operation that would require several dependent writes.
Lab D - Smoke matrix Scenario Expected
assign Workspace member Success
assign non-member 409 ASSIGNEE_NOT_WORKSPACE_MEMBER
set new due date in past 400 DUE_DATE_IN_PAST
set dueAt null Success; due date cleared
Exercise levels Level Challenge
1 - Follow Implement the reference rules and pass the PowerShell smoke checks.
2 - Modify Add a rule that CANCELED Tasks cannot receive a new assignee until restored to TODO.
3 - Implement Create a changeStatus(id,targetStatus) service method and make generic update delegate status changes through it.
4 - Engineer Design an approvePurchaseOrder() workflow with at least four invariants and identify exactly which steps must be transactional. Do not write code until the responsibilities are mapped.
Architecture oral exam • Why does Zod not own the assignee membership rule?
• Why should completedAt be server-derived?
• When is a single Prisma write enough without $transaction?
• Why does a controller delegate workflow decisions to a service?
• What evidence would justify extracting Task transition rules into another provider?
• How is a business invariant different from a database foreign key?
• Why is authorization not the same as membership-validity business logic?
Phase exit checklist • controllers remain thin and transport-focused.
• TasksService protects explicit Task workflow rules.
• invalid status transitions produce stable business errors.
• completedAt stays consistent with DONE/reopen behavior.
• Task assignees must belong to the Task workspace.
• business validation is distinct from Zod shape validation.
• transactions are used intentionally, not automatically.
• no Repository Pattern or unnecessary architecture layers were introduced.
• you can map the same service-layer reasoning to HRIS, payroll, procurement, and inventory use cases.
v
Controller = transport
v
TasksService = use case + invariants
v
v
PostgreSQL = durable integrity
TaskFlow now has a real application-service layer instead of database-driven CRUD.
Phase 15 adds Filtering, Search, Sorting & Pagination. We will design query parameters, safe dynamic Prisma filters, pagination trade-offs, index-aware access patterns, query DTOs, metadata, and API contracts for collection endpoints.
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: request → validated command → invariant → state transition → persisted 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: Refactored task service with explicit policies/invariants and thin controllers.. 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.
if (task.status === "DONE") {
throw new TaskAlreadyCompletedError(task.id);
}
task.status = "DONE";
task.completedAt = new Date();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.
Add a use-case method whose inputs/outputs make orchestration visible.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.Business rules duplicated in controllers and frontend
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.