1. Executive Overview 

Currently, Communication Service Providers (CSPs) have difficulties discovering new services available from the Add-on Mart, as it requires them to log in to a separate portal, investigate if this add-on is applicable or not. The objective of this project is to streamline this process by promoting Add-on Mart services within the relevant sections of the PortaBilling Admin UI and providing direct links to the Add-on Mart portal for subscription and configuration, thereby enhancing usability and reducing the time-to-market for new functionalities for CSPs.

2. Business Goals & Stakeholders 

3. User Stories 

• As a PortaBilling Administrator, I want to see Add-on Mart services that are relevant to a specific PortaBilling function (e.g., Payment Systems), so that I can easily discover new add-ons directly within PortaBilling Admin UI.
• As a PortaBilling Administrator, I want to view a brief description and an image for each promoted Add-on Mart service within PortaBilling, so that I can quickly understand its purpose and value.
• As a PortaBilling Administrator, I want to click a direct link from PortaBilling to the specific Add-on Mart page for a module, so that I can seamlessly navigate to subscribe or manage Add-on configuration.
• As a PortaBilling Administrator, I want to clearly identify if an Add-on is already subscribed to by my company directly from the PortaBilling Admin UI, so that I avoid redundant actions and know whether to subscribe or manage an existing service.
• As a PortaBilling Administrator, I want to know if an Add-on is in trial mode and its expiration date, so that I can focus on testing the add-on before it expires.
  
• As a PortaBilling Administrator, I want to know whether an Add-on has expired or is no longer in service (cancelled, suspended due to non-payment), so that I can troubleshoot customer complaints.
• As a PortaBilling Administrator, I want to know that the Add-on requires a newer PortaSwitch version so that I can plan the update with PortaOne support.
• As a PortaBilling Reseller, I want to discover Add-on Mart services that extend my offerings, so that I can offer new value-added services to my sub-resellers and customers faster.
• As a PortaBilling Reseller, I want to clearly identify if an Add-on Mart service is already subscribed to by my company directly from the PortaBilling Admin UI, so that I avoid redundant actions and know whether to subscribe or manage an existing service.
• As a PortaBilling Reseller, I want to know if an Add-on is in trial mode and its expiration date, so that I can focus on testing the add-on before it expires.
  
• As a PortaBilling Reseller, I want to know whether an Add-on has expired or is no longer in service (cancelled, suspended due to non-payment), so that I can troubleshoot customer complaints.
• As a PortaBilling Reseller, I want to know that the Add-on requires a newer PortaSwitch version, so that I can ask for the update.

4. Example of Use 

An Administrator configures a new payment system. The system presents a list of payment processors, distinguishing between 'Available on Add-on Mart' (e.g., Stripe) and 'Subscribed on Add-on Mart' options. The 'Available' processor shows its details and a 'Subscribe' button. Clicking 'Subscribe' redirects the Administrator to the Add-on Mart portal for subscription. Post-subscription, the processor's status in PortaBilling reflects 'Subscribed'.

5. Current Solution 

Currently, CSPs access Add-on Mart services externally, separate from the PortaBilling administration interface. Administrators must manually log into the addonmart.portaone.com to find, purchase, and activate services.
Only one person with the right to sign on behalf of company/right to purchase Add-Ons using a credit card can see the status of Add-Ons. While the administration on a daily basis is done by a different group of people - admins, resellers.

1. PortaBilling administrators and resellers may not know about the Add-ons available and their subscription status.
2. PortaBilling administrators can hardly discover new modules available.

6. Technical Constraints 

The solution must be implemented within the existing PortaBilling Admin and Reseller UI frameworks and potentially existing UI plug-in capabilities. The integration must ensure compatibility with the PortaBilling Admin/Reseller portal, potentially all other portals derived from the admin, meaning the distributor, representative or CC staff portals. The Add-on Mart portal will remain the authoritative source for subscription, payment, and detailed configuration management, with PortaBilling providing contextual links. The display of add-on information (name, description, image, subscription status) within PortaBilling will require communication with the Add-on Mart platform or a local cache/integration layer that can retrieve this information reliably.

7. Use Cases 

UC-1: Discover and Navigate to an Available Payment Processor Add-on 

Actors:

• PortaBilling Administrator

Preconditions:

• PortaBilling Administrator 'Alex Petrov' is logged into PortaBilling Admin UI.
• An Add-on Mart payment processor module, 'Stripe', is available for subscription but not yet subscribed by the CSP.
• The Administrator has navigation access to 'E-payments' -> 'Payment systems list'.

Scenario 1: Happy Path: Subscribe to a New Payment Processor

1. Administrator 'Alex Petrov' navigates to 'E-payments' > 'Payment systems'
2. Administrator 'Alex Petrov' wants to add a new payment system.
3. The system displays a list of payment processors, including 'Stripe' with the label 'Available on Add-on Mart'.
4. The system displays 'Stripe' with a short module description.
5. Administrator 'Alex Petrov' understands that 'Stripe' requires an additional subscription to the add-on mart module.
6. Administrator 'Alex Petrov' decides to subscribe for this module.
7. The system redirects Administrator 'Alex Petrov' to the specific 'Stripe' module page on the Add-on Mart portal (e.g., https://addonmart.portaone.com/management-ui/all-modules/stripe).
8. Administrator 'Alex Petrov' completes the subscription for 'Stripe' on the Add-on Mart portal.
9. Administrator 'Alex Petrov' returns to PortaBilling Payment Systems.
10. The system now displays 'Stripe' as available for configuration.

UC-2: Discover Call Recording Speech-to-Text Add-on and subscribe for a trial 

Actors:

• PortaBilling Administrator
• PortaBilling Reseller

Preconditions:

• PortaBilling Administrator 'Alex Petrov' is logged into PortaBilling Admin UI (or Reseller 'Jane Doe' logged into Reseller UI).
• An Add-on Mart speech-to-text module, 'Speech-to-text module from OpenAI', is available for subscription but not yet subscribed by the CSP.
• The user has navigation access to a product's 'Service configuration' -> 'Call recording' settings (e.g., for Product ID 3, Customer ID 10).

Scenario 2.1: Happy Path: Discover and Activate Trial

1. Administrator 'Alex Petrov' navigates to a 'Customer 123456' product settings: 
2. The system displays the call recording settings for the selected product/customer.
3. Administrator 'Alex Petrov' observes a 'Speech-to-text module from OpenAI'.
4. Administrator 'Alex Petrov' decides to learn more.
5. The system redirects Administrator 'Alex Petrov' to the specific 'Speech-to-text module from OpenAI' page on the Add-on Mart portal (e.g., https://addonmart.portaone.com/modules/speech-to-text).
6. Administrator 'Alex Petrov' reviews the module details on the Add-on Mart portal and activates the trial at 2025-03-19 10:20 UTC.
7. The system shows 'Speech-to-text module from OpenAI' available for configuration in PortaBilling.

Scenario 2.2 (alternative to 2.1): The add-on is discoverable, but not compatible with the PortaSwitch version

1. Administrator 'Alex Petrov' navigates to a 'Customer 123456' Call Recording settings.
2. Administrator 'Alex Petrov' observes  'Speech-to-text module from OpenAI'.
3. The section contains a short description ('Effortless calls and voicemail transcriptions from OpenAI'), an OpenAI logo, and 'Requires MR125'.
4. Administrator 'Alex Petrov' understands that PortaSwitch has to be updated before he can subscribe.

Scenario 2.3: Add-on is on trial

1. On 2025-03-20 10:45 UTC, Administrator 'Alex Petrov' navigates to a specific customer's product Call Recording settings.
2. Administrator 'Alex Petrov' observes  'Speech-to-text module from OpenAI'.
3. Administrator 'Alex Petrov' sees information that 'Speech-to-text module from OpenAI' is on trial until 2025-04-18 (ends in 29 days). 
4. Administrator 'Alex Petrov' sees the 'Subscribe to a paid version' message.

Scenario 2.4: Trial expires

1. On 2025-04-21 10:45 UTC, Administrator 'Alex Petrov' gets a complaint from a customer - call transcriptions do not work.
2. Administrator 'Alex Petrov' navigates to a specific customer's product Call Recording settings.
3. The system displays that 'Speech-to-text module from OpenAI' trial has expired.
4. The system invites to 'Subscribe to a paid version'

Scenario 2.5: Paid subscription activation (continues after 2.4)

1. Administrator 'Alex Petrov'  decides to 'Subscribe to a paid version'.
2. The system redirects to Add-On mart, where Administrator 'Alex Petrov' activates the paid subscription. 
3. Administrator 'Alex Petrov'  returns to PortaBilling interface and sees 'Speech-to-text module from OpenAI' as working, paid subscription active.

Scenario 2.6: Paid subscription suspension on non-payment (continues after 2.5)

1. Add-On Mart fails to charge the credit card for the paid subscription to the services, and service suspension starts.
2. On 2025-07-03 12:45 UTC, Administrator 'Alex Petrov' gets a complaint from a customer - call transcriptions do not work.
3. Administrator 'Alex Petrov' navigates to a specific customer's product Call Recording settings.
4. Administrator 'Alex Petrov' sees information that 'Speech-to-text module from OpenAI' is suspended.
5. The system invites to renew paid subscription.

 Scenario 2.7: Paid subscription reactivation (continues after 2.6)

1. Administrator 'Alex Petrov'  decides to renew paid subscription, Add-On mart opens in the browser.
2. Administrator 'Alex Petrov' resolves the issue with payments in the Add-On mart.
3. Add-On mart reactivates the service.
4. Administrator 'Alex Petrov' returns to the PortaBilling interface and sees 'Speech-to-text module from OpenAI' as working, paid subscription active.

8. UI prototypes

9. Non-Functional Requirements 

Usability 

1. Intuitive Discovery: The promotion of Add-on Mart services within PortaBilling Admin UI shall be visually distinct and easily recognizable by administrators and resellers, aligning with PortaBilling's existing UI/UX guidelines.
2. Clear Status Indication: The subscription status of an Add-on Mart module (available vs. subscribed) shall be clearly and consistently indicated across all relevant PortaBilling Admin UI elements (e.g., dropdowns, side panels).
3. Direct Navigation: Clicking on the 'Subscribe' or 'Manage' link for an Add-on Mart module shall directly navigate the user to the precise module page within the Add-on Mart portal, minimizing unnecessary clicks and navigation steps.

Performance 

1. Fast Loading: The display of Add-on Mart module information (name, description, image, status) within PortaBilling shall not introduce noticeable delays in page loading or UI responsiveness (e.g., less than 500ms for initial display).
2. Efficient Updates: The system shall efficiently update the subscription status of Add-on Mart modules within PortaBilling, reflecting changes made in the Add-on Mart portal with minimal latency (e.g., within 5 minutes of a status change).

Reliability 

1. Link Integrity: All links provided from PortaBilling to the Add-on Mart portal shall be consistently functional and point to the correct Add-on Mart module pages.
2. Information Accuracy: The module name, description, image, and subscription status displayed within PortaBilling shall accurately reflect the current information from the Add-on Mart.
3. Graceful Degradation: In case of a temporary unavailability or error in communicating with the Add-on Mart, the PortaBilling Admin UI shall degrade gracefully, displaying an appropriate message without interrupting core PortaBilling functionalities.

Security 

1. Access Control: Access to view Add-on Mart promotions and links within PortaBilling shall adhere to the existing PortaBilling role-based access control for administrators and resellers.
2. Data Privacy: No sensitive customer or billing data from PortaBilling shall be transmitted to the Add-on Mart without explicit user action and consent during the linking process.
3. Secure Redirection: Redirection to the Add-on Mart portal shall utilize secure protocols (HTTPS) and prevent potential security vulnerabilities like open redirects.

Maintainability 

1. Configurable Promotions: The system shall allow PortaOne to easily configure and update the list of promoted Add-on Mart modules, their descriptions, images, and target links without requiring PortaBilling software updates.
2. Scalability: The integration shall be capable of scaling to accommodate a growing number of Add-on Mart modules and PortaBilling users without degrading performance.