Task Status Workflow and Derived State

Task Status Workflow & Derived State Explicit transitions, completedAt consistency, and operations with business meaning

Phase 14 - Service & Business Logic Architecture Volume 04 - Professional Backend

Architecture milestone

Current Task status

v

Transition policy

v

Derived state

v

Persist

Phase 14 turns CRUD-oriented service methods into explicit application rules and workflows while keeping infrastructure simple.

Model Task status as a workflow, not a free-form field Zod can prove that a status value is one of TODO, IN_PROGRESS, DONE, or CANCELED. It cannot decide whether a specific transition is allowed from the current persisted state. That requires reading the Task and applying workflow policy.

const ALLOWED_STATUS_TRANSITIONS = { TODO: [IN_PROGRESS, CANCELED], IN_PROGRESS: [TODO, DONE, CANCELED], DONE: [IN_PROGRESS], CANCELED: [TODO], };

From Allowed next states

TODO IN_PROGRESS, CANCELED

IN_PROGRESS TODO, DONE, CANCELED

DONE IN_PROGRESS

CANCELED TODO

Figure 1 - Status transition reasoning

Read current status

v

Requested status differs?

v

Check transition policy

v

Reject invalid transition with 409

v

Apply derived side effects

v

Persist valid update

The update becomes an application operation, not an arbitrary column assignment.

Derived state: completedAt When Task status changes to DONE, TaskFlow records completedAt. When a DONE Task is reopened, completedAt is cleared. That makes status and completion timestamp internally consistent.

if (to === TaskStatus.DONE) return new Date(); if (from === TaskStatus.DONE) return null;

Why not let the frontend set completedAt?

The client may request a business action such as completing a Task, but the server owns the authoritative timestamp and invariant. Otherwise clients can create contradictory states such as status=TODO with completedAt populated.

CRUD field update vs business operation PATCH remains a valid transport for this phase, but TasksService interprets status as a workflow change rather than blindly forwarding it. In larger domains, an explicit operation such as POST /purchase-orders/:id/approve can be clearer than a generic field patch because approval has business meaning and side effects.