Enterprise Subscription Management & Reminder System

A production-grade subscription management platform built with enterprise scalability and security in mind. This system provides comprehensive user management, subscription lifecycle automation, and intelligent renewal workflows for SaaS and service businesses.

🚀 Enterprise Features

🔐 Advanced Security & Authentication

• JWT-based authentication with secure token handling
• Email verification system for new accounts with secure token management
• Role-based access control (RBAC) with granular permissions:
  • admin: Full system access
  • manager: User and subscription management
  • support: Limited read access for customer service
  • user: Self-service capabilities
• Arcjet protection for advanced rate limiting and bot detection

💼 Enterprise Subscription Management

• Complete subscription lifecycle:
  • Creation with customizable billing terms
  • Smart renewal handling with configurable frequencies
  • Automated status transitions
  • Extension, pause, and resume capabilities
• Trial management:
  • Configurable trial periods
  • Seamless trial-to-paid conversion
  • Trial analytics and conversion tracking
• Flexible billing options:
  • Multiple currencies support
  • Various payment method tracking
  • Custom pricing plans

⏰ Intelligent Reminder Workflows

• Event-driven architecture using Upstash QStash serverless workflows
• Multi-stage reminder sequences:
  • Configurable reminder intervals (7, 5, 2, and 1 days before renewal)
  • Smart reminder delivery based on user engagement
  • Automatic rescheduling when subscription terms change
• Durable execution with error recovery and state persistence
• Real-time monitoring through admin dashboard

🛠️ Advanced Technical Features

• Comprehensive audit logging for all subscription changes
• Optimization for high-volume operations with efficient MongoDB queries:
  • Industry grade global pagination middleware for MongoDB models
  • Cursor-based pagination for QStash workflow IDs
• Rate limiting to prevent API abuse
• Robust error handling with detailed error logging
• Pagination throughout all list endpoints for handling large datasets
• Field selection to optimize payload size and network usage

📊 System Architecture

API Layers

The system follows a clean, modular architecture:

graph TD
  A[API Routes] --> B[Controllers]
  B --> C[Services/Business Logic]
  C --> D[Data Access Layer]
  D --> E[(MongoDB)]
  
  F[Authentication Middleware] --> A
  G[RBAC Middleware] --> A
  H[Validation Middleware] --> A
  I[Rate Limiting] --> A
  
  C <--> J[Workflow Engine]
  J <--> K[(QStash)]
  J --> L[Email Service]

Loading

Security Architecture

Defense-in-depth approach with multiple security layers:

graph LR
  A[Client Request] --> B[TLS/SSL]
  B --> C[Rate Limiting]
  C --> D[JWT Authentication]
  D --> E[RBAC Authorization]
  E --> F[Input Validation]
  F --> G[Business Logic]
  G --> H[Data Access Control]
  H --> I[(Database)]

Loading

🛠️ Technology Stack

• Backend: Node.js, Express
• Database: MongoDB with Mongoose ODM
• Authentication: JWT with bcryptjs
• Email: Nodemailer
• Workflow Engine: Upstash QStash
• Date Handling: Day.js
• Security: bcryptjs, Arcjet (rate limiting & bot protection)
• Logging: Morgan

📝 API Reference

Authentication Routes

Method	Endpoint	Description	Access
POST	/api/v1/auth/register	Create new account	Public
GET	/api/v1/auth/activate/:token	Verify email address & Activate account	Public
POST	/api/v1/auth/login	Authenticate user	Public
POST	/api/v1/auth/logout	Logout	Authenticated

User Management Routes

Method	Endpoint	Description	Access
GET	/api/v1/users	List all users (paginated)	Admin, Manager, Support
GET	/api/v1/users/me	Get current user profile	Any authenticated user
GET	/api/v1/users/:id	Get user by ID	Admin, Manager, Support, Self
POST	/api/v1/users	Create new user	Admin, Manager
PUT	/api/v1/users/:id	Update user	Admin, Manager, Self
DELETE	/api/v1/users/:id	Delete user	Admin

Subscription Management Routes

Method	Endpoint	Description	Access
GET	/api/v1/subscriptions	List all subscriptions	Admin, Manager
GET	/api/v1/subscriptions/:id	Get subscription by ID	Admin, Manager, Owner
POST	/api/v1/subscriptions	Create subscription	All authenticated
PUT	/api/v1/subscriptions/:id	Update subscription	Admin, Manager, Owner
DELETE	/api/v1/subscriptions/:id	Delete subscription (Soft Delete)	Admin, Manager, Owner
GET	/api/v1/subscriptions/upcoming-renewals	Get upcoming renewals	Admin, Manager
GET	/api/v1/subscriptions/user/:id	Get user subscriptions	Admin, Manager, Owner
PUT	/api/v1/subscriptions/:id/extend	Extend subscription	Admin, Manager
PUT	/api/v1/subscriptions/:id/pause	Pause subscription	Admin, Manager, Owner
PUT	/api/v1/subscriptions/:id/resume	Resume subscription	Admin, Manager, Owner
PUT	/api/v1/subscriptions/:id/cancel	Cancel subscription	Admin, Manager, Owner
POST	/api/v1/subscriptions/:id/trial	Start trial	Admin, Manager
POST	/api/v1/subscriptions/:id/convert	Convert trial to active	Admin, Manager, Owner
GET	/api/v1/subscriptions/:id/history	Get subscription history	Admin, Manager, Owner
PATCH	/api/v1/subscriptions/:id/auto-renew	Toggle auto-renewal	Admin, Manager, Owner
POST	/api/v1/subscriptions/:id/renew	Manually renew subscription	Admin, Manager

Admin Workflow Management Routes

Method	Endpoint	Description	Access
GET	/api/v1/utilities/workflows/active	List active workflows	Admin
GET	/api/v1/utilities/workflows/:workflowId	Get workflow details	Admin
DELETE	/api/v1/utilities/workflows/:workflowId	Cancel workflow	Admin
POST	/api/v1/utilities/workflows/fix-orphaned	Fix orphaned workflows	Admin

Direct Workflow API (Administrative)

Method	Endpoint	Description	Access
POST	/api/v1/workflows/subscription/reminder	Create/Update reminders	Admin, System

🧩 Subscription Lifecycle States

stateDiagram-v2
    [*] --> pending: Create
    pending --> active: Activate
    pending --> trial: Start Trial
    
    trial --> active: Convert
    trial --> canceled: Cancel
    trial --> expired: Expire
    
    active --> paused: Pause
    paused --> active: Resume
    
    active --> canceled: Cancel
    active --> deleted: Delete (Soft Delete)
    active --> expired: Expire
    
    canceled --> [*]: Permanent
    deleted --> [*]: Permanent
    expired --> [*]: Permanent

Loading

📊 Admin Dashboard

The system includes an admin interface for subscription management:

• User Management:

  • View and manage users by role
  • Basic user information and subscription status

• Subscription Oversight:

  • View all active subscriptions
  • Monitor upcoming renewals with findUpcomingRenewals
  • Track subscription statuses across the platform

• Workflow Monitoring:

  • View active reminder workflows
  • Fix orphaned workflows with utility endpoints
  • Track reminder states for subscriptions

• Basic Analytics:

  • Calculate total subscription costs with calculateTotalCost
  • View subscription durations and renewal metrics
  • Track active subscriptions per user

🔧 Installation & Setup

Prerequisites

• Node.js 16+ (LTS recommended)
• MongoDB 4.4+
• Upstash QStash account
• Email service provider (nodemailer)

Development Setup

# Clone repository
git clone https://github.com/your-org/subscription-api.git
cd subscription-api

# Install dependencies
npm install

# Configure environment
# Choose the appropriate environment file depending on your setup
cp .env.development.local .env   # For development
# OR
cp .env.production.local .env    # For production

# Edit the .env file with your configuration

# Run QStash CLI in a separate terminal for workflow processing (Local Testing)
npx @upstash/qstash-cli dev

# Start development server
npm run dev

📝 Environment Variables

Development

# Server
PORT=3000
SERVER_URL=https://api.yourdomain.com

# ENV
NODE_ENV=development

# Database
DB_URI=mongodb+srv://username:password@cluster.mongodb.net/subscription-api

# Authentication
JWT_SECRET=<your_secret_key_here>
JWT_EXPIRES_IN=1d

# Upstash QStash
UPSTASH_QSTASH_TOKEN=<your_qstash_token>
UPSTASH_QSTASH_URL=https://qstash.upstash.io/v1/publish

# Arcjet
ARCJET_KEY=your_arcjet_key
ARCJET_ENV=your_arcjet_site_key

# Nodemailer
EMAIL = <your_email>
EMAIL_PASSWORD=<your-email-16-character-long-app-password>

For Production: Change NODE_ENV to production and include QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY

🔒 Security Features

• Password Security:

  • bcrypt hashing with appropriate salt rounds
  • Password strength validation
  • Brute force protection

• JWT Security:

  • Secure token signing with strong secrets
  • Proper token validation
  • Protected routes with authentication middleware

• API Security:

  • CORS protection with appropriate origins
  • Arcjet for advanced bot detection
  • Rate limiting with Arcjet Shield
  • XSS and CSRF protection

• Data Security:

  • Input validation on all endpoints
  • Parameterized queries to prevent injection
  • Field-level access control

🤝 Contributing

We welcome contributions to this project! If you'd like to contribute, please follow these steps:

1. Fork the repository.
2. Create a new branch: git checkout -b <branch_name>.
3. Make your changes and commit them: git commit -m '<commit_message>'.
4. Push to your branch: git push origin <branch_name>.
5. Create the pull request.

Alternatively, see the GitHub documentation on creating a pull request.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ by Roshis Rai