Subscription Tracker API

A production-style backend built to be taken apart - every transaction, token and workflow step annotated with what it guarantees and where it stops.

Stack - Node.js, Express, MongoDB via Mongoose, jsonwebtoken + bcrypt, Arcjet, Upstash Workflow / QStash, dayjs. ESM throughout.

Every request runs the same gauntlet

Express runs middleware in the order it’s attached, so the order is a design decision, not an accident. This is the path a request takes before it reaches a controller.

1. 01

   Body & cookie parsers

   express.json(), express.urlencoded() and cookie-parser go first, so req.body and req.cookies are already populated for everything downstream. Nothing after this has to re-parse the request.

2. 02

   Arcjet

   Runs after the parsers so it can read the parsed request. A single protect() call carries three rules: a shield against injection-style attacks, a bot rule that allows the search-engine category and blocks the rest, and a token bucket - a 10-request burst per IP, then a refill of 5 every 10 seconds. A denied decision maps to 429 for the rate limit, 403 for a bot, 403 otherwise.

3. 03

   authorize (per write route)

   Pulls the token out of the Authorization: Bearer header, runs jwt.verify against the secret, looks the user up by the id in the payload, and hangs that document off req.user. A tampered, expired or malformed token makes verify throw synchronously, so control jumps straight to the catch and the database is never touched.

4. 04

   Error handler

   Signature (err, req, res, next), mounted dead last so it catches next(err) from every route above. It rewrites Mongoose failures into clean status codes - a bad ObjectId to 404, a duplicate key to 400, a validation error flattened into one 400 - and falls back to 500.

One ordering bug lives inside the router too: /upcoming-renewals has to be declared above /:id, or Express matches the literal path as an id and the wrong handler runs.

Auth, taken apart

A bcrypt-hashed password at sign-up, then a JWT signed with a server secret on every request after. bcrypt.genSalt(10) sets the work factor; sign-in re-hashes the attempt and compares. The interesting part was pinning down where the token’s job ends.

const session = await mongoose.startSession();
session.startTransaction();
// ... create user, sign token ...
await session.commitTransaction();   // catch -> session.abortTransaction()

Notes left in the model layer

subscriptionSchema.pre('save', function () {
  if (!this.renewalDate || this.isModified('startDate') || this.isModified('frequency')) {
    this.renewalDate = addDays(this.startDate, PERIOD[this.frequency]);
  }
  if (this.status !== 'cancelled')
    this.status = this.renewalDate < new Date() ? 'expired' : 'active';
});

Object.assign(sub, req.body);   // update: merge an unknown-shape payload
sub.status = 'cancelled';        // cancel: one known field
await sub.save();                // NOT findByIdAndUpdate

Subscription.findById(id).populate('user', 'name email')

const subscription = await Subscription.create({
  ...req.body,
  user: req.user._id,   // from authorize, never from the client body
});

The reminder workflow

Reminders don’t run off a cron job polling the table. Each subscription gets its own Upstash workflow - a durable function that can sleep for days and survive a restart mid-run.

One interop snag

The project is ESM ("type": "module"), so only import works - but @upstash/workflow/express ships as CommonJS. The workaround is to synthesise a require inside the module:

import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const { serve } = require('@upstash/workflow/express');

What I took away

• Atomic transactions - a MongoDB session that commits in full or aborts and leaves nothing behind, and the failure modes that trigger the abort (a violated constraint, a type mismatch, a bad query).
• What signing a JWT actually protects - integrity and authenticity - versus what it doesn't: the payload is readable by anyone, and transport and revocation are separate problems with separate fixes.
• The three-layer view of the whole thing: TLS for confidentiality in transit, the signature for integrity, hashing for confidentiality at rest.
• Why stateless auth lets an old token keep working, and the three ways around it - a Redis blocklist, a tokenVersion stamp, or short tokens with refresh - plus why a second browser tab is already logged in (the cookie store is shared across tabs on a domain).
• Mongoose lifecycle hooks, and why findByIdAndUpdate and other query-level writes skip them; populate() as a projected JOIN.
• Durable execution - checkpointing a read with context.run so a retry reuses it, and suspending a workflow for days with sleepUntil instead of a cron job or a long-lived timer.
• Express middleware runs top to bottom, so parsers precede security and the error handler comes last; and route order matters - a literal path has to be declared before a :param that would otherwise swallow it.
• Pulling a CommonJS package into an ESM project with createRequire.

Structure and stack follow JavaScript Mastery’s production-backend walkthrough. The annotations throughout the code - what each mechanism guarantees and where it stops - are my own. Source is linked above.