Skip to content

Overview

Relevant source files - CHANGELOG.md - README.md - app.js - package.json

The Subscription Tracker API is a production-ready backend service built with Node.js and Express. It provides a comprehensive solution for managing user subscriptions, handling secure authentication, and automating email notifications for upcoming renewals through a sophisticated workflow engine.

The system is designed with a layered architecture, utilizing MongoDB for data persistence, Upstash for asynchronous workflow orchestration, and Arcjet for advanced security.

System Capabilities

The API automates the lifecycle of a subscription, from creation to expiration. Key functionalities include:

  • Secure Authentication: JWT-based auth with bcryptjs for password hashing package.json14-21
  • Subscription Management: CRUD operations with automatic calculation of renewal dates and status tracking README.md9-10
  • Automated Workflows: Integration with Upstash Workflow to schedule and send reminder emails at specific intervals (e.g., 7, 5, 2, and 1 day before renewal) app.js13README.md11
  • Security & Rate Limiting: Request protection using Arcjet for bot detection and token-bucket rate limiting app.js12-25
  • Interactive Documentation: Integrated Swagger UI for API exploration and testing app.js32-40

For a step-by-step setup guide, see Getting Started.

Technology Stack

The project leverages a modern ESM-based Node.js stack package.json5:

Category Technology Usage
Runtime Node.js (v18+) Core execution environment README.md3
Framework Express.js Web server and routing package.json20
Database MongoDB / Mongoose Data modeling and persistence package.json23
Security Arcjet WAF, Bot detection, and Rate limiting package.json12
Workflows Upstash QStash Asynchronous scheduling and reminders package.json13
Email Nodemailer / Brevo SMTP delivery for notifications package.json25

High-Level Architecture

The application follows a modular, controller-based pattern where the app.js entry point initializes the Express application, connects to the database, and mounts various route handlers.

System Flow Diagram

The following diagram illustrates how a request flows from a client through the security layers into the core business logic and external services.

Sources:app.js16-31middlewares/arcjet.middleware.jsmiddlewares/auth.middleware.jsroutes/subscription.routes.js

Code Entity Mapping

This diagram maps the logical subsystems to their primary implementation files in the codebase.

Sources:app.js7-14README.md98-150

Subsystem Overviews

Request Protection

Every request (except health checks and documentation) passes through the arcjetMiddlewareapp.js25 This layer performs security checks before the request reaches the routing logic.

Authentication

The system uses a Bearer token strategy. The authorize middleware in middlewares/auth.middleware.js validates the JWT and attaches the user entity to the request object (req.user) for downstream controllers.

Subscription Lifecycle

When a subscription is created via POST /api/v1/subscriptions, the createSubscription controller saves the record to MongoDB and immediately triggers an Upstash workflow README.md206 This workflow manages the "sleep-and-notify" logic for renewal reminders.

Project Organization

The codebase is organized into functional directories to separate concerns:

  • controllers/: Business logic and request handling.
  • models/: Mongoose schemas and data validation.
  • routes/: URL path definitions.
  • middlewares/: Request pre-processing and security.

For a detailed breakdown of the file system, see Project Structure.

Sources: