AG
2025-01-15•7 min read

Building TaskFlow against a spec — NestJS, Next.js, and no free-form status changes

A task management platform built the unglamorous way: SRS first, endpoint-to-requirement traceability, rotating refresh tokens, and a task lifecycle you can't corrupt. What each decision bought — and what it cost.

NestJSNext.jsTypeScript

Most task-management tutorials end where the interesting part begins: one user, one table, no rules. TaskFlow started from the opposite end — a full software requirements specification written before any code, and every feature traced back to it. This post is about what that discipline bought, what it cost, and the decisions I'd defend in a design review.

Decision 1: the spec is the arbiter, not the backlog

I wrote an SRS (functional and non-functional requirements, business rules, scope) before touching NestJS, and I maintain an API parity matrix — every endpoint mapped to the requirement IDs it fulfills.

The trade-off is real: I spent days writing requirements I later implemented differently. But the payoff showed up constantly. When I wanted to add a shiny feature mid-build, the answer wasn't a mood — it was "which requirement is this?" No answer, no feature. And when I needed to prove a module was done, "done" was checkable against a line in a document, not a feeling.

The discipline even lives in the code comments:

// FR-009.2: record the true completion time (updatedAt is unreliable —
// it changes on any edit, not just completion). Cleared when reopened.
updateData.completedAt = newStatus === TaskStatus.DONE ? new Date() : null;

That requirement ID is the traceability chain, six months later, at the exact line where it matters.

Decision 2: MongoDB + Mongoose, with typed edges everywhere

The data layer is MongoDB through Mongoose — a deliberate fit for a project whose task and sprint shapes evolved weekly during the build. The type safety doesn't come from the ODM alone; it comes from layers: Mongoose schemas at the bottom, DTOs with class-validator at the edge (whitelist mode, non-whitelisted properties forbidden), and TypeScript strict mode across all 11 feature modules.

The trade-off versus a relational setup: no joins, so reporting queries shape their own aggregations. For burndown analytics — which needs sprint history plus completion timestamps — that's an aggregation pipeline, not a SQL query. Manageable, and the schema freedom paid for itself many times during iteration.

Decision 3: refresh tokens that rotate and remember betrayal

Auth is JWT access tokens plus rotating refresh tokens with reuse detection: every refresh invalidates the old token and issues a new one; presenting an already-used refresh token revokes the whole family.

The trade-off: this adds a per-refresh database check and a token-family record — pure stateless JWT would be simpler and faster. What it buys: a stolen refresh token is a one-time-use weapon. The moment the legitimate client and an attacker both present the same token, reuse detection fires and the family dies. For a system holding other people's project data, "simpler" wasn't the right trade.

Decision 4: guards, not hope

Authorization is two global layers: a role guard enforcing the hierarchy (Administrator > ProjectManager > TeamMember) and a project-access guard ensuring members only touch tasks and projects they belong to. Controllers declare what they need; the guards enforce it before any controller code runs.

The alternative — checking roles inside each service method — spreads the same decision across 50 call sites and guarantees you'll forget one. Centralizing it costs more upfront structure and means every endpoint pays the guard overhead. The payoff is that a new endpoint is safe by default: you'd have to actively opt out of authorization, not remember to opt in.

Decision 5: no free-form status changes

Task status is a state machine, enforced server-side:

const allowedTransitions = VALID_TRANSITIONS[currentStatus];
if (!allowedTransitions.includes(newStatus)) {
  throw new BadRequestException(
    `Cannot transition task from "${currentStatus}" to "${newStatus}". ` +
      `Allowed transitions from "${currentStatus}": ${allowedTransitions.join(', ')}`,
  );
}

Backlog → To Do → In Progress → In Review → Done → Archived — and nothing else. The cost is obvious: sometimes you want Done → In Progress for a reopened task, and that path had to be designed (with its own cleanup rules — reopening clears stale deadline alerts). Free-form status editing would have taken ten minutes to build.

What it buys is everything downstream: the burndown chart is computed from completion timestamps that only the state machine can write, and the activity audit trail records transitions that are legal by construction. Analytics built on an enforced lifecycle are trustworthy; analytics built on a free-text status field are decoration.

Verification, not vibes

  • 197 unit tests across 19 suites — services, repositories, guards, pipes, the deadline cron, notification listeners
  • E2E smoke tests — real HTTP flows against the production guard stack with in-memory MongoDB (mongodb-memory-server), so tests are hermetic: no shared database state, no ordering flukes
  • CI runs backend lint → tests → build → e2e, and frontend lint → build on every push

What I'd defend in an interview

Not the feature list — those are table stakes for a task manager. The decisions: a spec that outvoted my enthusiasm, tokens that detect their own theft, guards that make endpoints safe by default, and a state machine that makes the analytics honest. Each one cost me time upfront. Each one is why the system can be reasoned about — by me, or by the next engineer who reads it.