1. Overview

This document outlines the design of a yearly subscription model that allows customers to subscribe and utilize services across multiple applications. Each application has unique user identifiers (e.g., user_key/email for application1, phone_number for application2). The system ensures efficient subscription management, renewal, cancellation, and analytics tracking.

2. Business Requirements

2.1 Key Features

Customers can purchase a yearly subscription applicable to multiple applications.

Each application identifies users differently (e.g., email, Phone Number).

Subscription plans include different service usage limits per application.

Users can renew subscriptions before expiry or after a grace period.

The system should support subscription analytics and KPIs.

2.2 Subscription Lifecycle

Subscription Creation – Users subscribe to a plan and associate multiple applications.

Subscription Utilization – Applications validate access based on the user’s subscription.

Renewal – Users can renew subscriptions manually or automatically.

Cancellation – Users can cancel subscriptions, and refunds (if applicable) are processed.

Analytics & Reporting – The system captures detailed subscription activity for insights.

3. System Design

3.1 Entity-Relationship Diagram (ERD)

Entities and Relationships:

Users (UserID, Name, Email, ContactInfo)

Subscriptions (SubscriptionID, UserID, PlanID, StartDate, EndDate, Status)

Applications (ApplicationID, Name, IdentifierType)

ApplicationMappings (MappingID, SubscriptionID, ApplicationID, UniqueIdentifier)

SubscriptionLimits (LimitID, SubscriptionID, ApplicationID, UsageLimit, RenewalCycle)

Payments (PaymentID, SubscriptionID, Amount, PaymentDate, Status)

Plan (PlanID, PlanType, Amount)

SubscriptionHistory (HistoryID, SubscriptionID, ChangeDate, ChangeType)

3.2 System Architecture Diagram

User Authentication: Keycloak for secure authentication.

Microservices:
- Subscription Service: Manages subscription creation, updates, and cancellations.
- Payment Service: Handles payment processing and transaction records.
- Analytics Service: Tracks subscription metrics and KPIs.
- Notification Service: Sends alerts for renewals, cancellations, and usage limits.

Storage & Processing:
- AWS RDS for structured data.
- AWS S3 for logs and reports.
- Redis for caching subscription validations.
- AWS SNS/SQS for event-based communication.

4. API Design

4.1 Subscription Management APIs

4.1.1 Create Subscription

Endpoint: POST /subscriptions

Request Body:{ "user_id": "12345", "plan_id": "yearly_premium", "applications": [ { "application_id": "1", "identifier": "user@example.com" }, { "application_id": "2", "identifier": "9734532342" } ] }

Response: Subscription ID with status.

4.1.2 Validate Subscription

Endpoint: GET /subscriptions/validate?application_id=1&identifier=user@example.com

Response:{ "valid": true, "plan": "yearly_premium", "remaining_usage": 10 }

4.1.3 Renew Subscription

Endpoint: POST /subscriptions/{id}/renew

4.1.4 Cancel Subscription

Endpoint: POST /subscriptions/{id}/cancel

4.2 Analytics APIs

4.2.1 Get Subscription Insights

Endpoint: GET /analytics/subscriptions

Response:{ "active_subscriptions": 1000, "churn_rate": 5.2, "renewal_rate": 80.5 }

5. Data Storage Strategy

5.1 Tables and Indexing

“ (Primary table storing subscription details)

“ (Links subscriptions to applications)

“ (Defines usage limits per application and per plan)

“ (Stores payment records)

“ (Tracks all subscription changes)

Indexing on status, user_id, and application_name for quick lookups.

5.2 Data Retention

Active subscriptions: Stored indefinitely.

Expired/Canceled subscriptions: Archived after 2 years.

Payment transactions: Retained for financial compliance.

Usage analytics: Retained for up to 5 years for business insights.

6. Analytics & KPIs

6.1 Subscription Metrics

Active Subscriptions: Total ongoing subscriptions.

Churn Rate: Percentage of users canceling subscriptions.

Renewal Rate: Percentage of users renewing after expiry.

Revenue Trends: Subscription revenue growth over time.

6.2 Usage Tracking

Service Consumption: Monitors if users reach usage limits per application.

Application Engagement: Tracks which applications users interact with the most.

6.3 Payment Analytics

Payment Success Rate: Percentage of successful transactions.

Subscription Upgrade Rate: How many users switch to higher-tier plans.

6.4 Fraud Detection KPIs

Subscription Sharing Detection: Identifies unusual patterns of usage.

Chargeback Rate: Percentage of users requesting refunds.

7. Deployment Strategy

7.1 Backend Architecture

AWS RDS (MySQL/PostgreSQL) for database storage.

Spring Boot Microservices deployed on AWS ECS Fargate.

AWS API Gateway to manage API requests.

Redis for caching frequently accessed data.

7.2 Monitoring & Alerts

AWS CloudWatch for logs and API request tracking.

AWS X-Ray for performance monitoring.

AWS SNS/SES for subscription expiry notifications.

8. Summary

The designed subscription system ensures scalability, cross-application support, and insightful analytics. It provides a seamless experience for users while allowing administrators to monitor subscription trends and revenue efficiently.

Next Steps

Finalize API endpoints and database schema.

Implement a role-based dashboard for managing subscriptions.

Integrate with PayPal for automated payments.

Develop detailed ERD (Entity Relationship Diagram) and System Architecture Diagram.

                     +---------------------------------------+
                     |       Subscription API Gateway       |
                     +---------------------------------------+
                                       |
  +-------------------------------------------------------------+
  |                  Central Subscription Service (CSS)         |
  |  - Subscription Management                                   |
  |  - Identity Mapping (user_key, USDOT, etc.)                 |
  |  - Payment & Billing Integration                            |
  |  - Subscription Validation API                              |
  +-------------------------------------------------------------+
                                       |
           +-------------------------------------+
           |   External Payment Gateway (PayPal)|
           +-------------------------------------+
                                       |
  +-------------------------------------------------------------+
  |                    Notifications Service                       |
  |  - Renewal Reminders                                        |
  |  - Payment Failure Alerts                                   |
  +-------------------------------------------------------------+
                                       |
  +-------------------------------------------------------------+
  |              Admin Panel / Reporting Dashboard      |
  |  - User Subscription Tracking                              |
  |  - Payment & Billing Reports                               |
  +-------------------------------------------------------------+

Prepared by: Tech Team
Date: April 2025