Plan Store & Self-Service Checkout Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial & Business Value)
3. 🎯 User Roles & Key Capabilities
4. Plan Catalog & Multi-Tier Filter Navigation
5. Elastic Sizing & Interactive Checkout Modal
6. Instant Tenant Domain & SIP Trunk Provisioning Handshake
7. Troubleshooting & Verification
8. Glossary

---

1. Module Overview (Technical)

The Plan Store module (PlanCatalogPage.tsx, SubscribePlanModal.tsx, and clientService.ts) enables clients in the Ring2All Billing Client Portal to browse public telecom service tiers, customize voice capacity (extensions, simultaneous channels, recording storage), and complete instant self-service activations backed by multi-tenant provisioning.

sequenceDiagram
    autonumber
    actor Client as Customer Portal
    participant API as Ring2All Billing API
    participant DB as PostgreSQL (ss_billing)
    participant Core as Ring2All Core (PBX & SBC)

    Client->>API: GET /api/client/plans/catalog
    API->>DB: SELECT * FROM plans WHERE is_active = true ORDER BY price ASC
    DB-->>API: Active retail service plans
    API-->>Client: 200 OK (Catalog with steps, pricing & features)

    Client->>API: POST /api/client/subscriptions { planId, domainName, customExtensions, customChannels }
    API->>DB: Verify customer wallet balance & anti-fraud quotas
    API->>Core: Provision Tenant Domain (Telephony Server Directory / Sofia Profile)
    API->>Core: Provision SIP Account / Trunk (Kamailio SBC Dispatcher)
    API->>DB: INSERT INTO subscriptions (status='active', external_id=domain)
    DB-->>API: Subscription ID & Timestamps
    API-->>Client: 201 Created (Instant Activation & Realm URL)

Key Technical Capabilities

• Dynamic Step Pricing: Calculates prices in real time based on configured step increments (e.g., +$10.00 / 5 ext and +$5.00 / 2 ch) for elastic PBX plans.
• Instant Handshake Orchestration: Automatically provisions voice domains on Telephony Server and registers SIP endpoints on the perimeter SBC without human intervention.
• Multi-Category Filtering: Client-side category filtering seamlessly segments plans into All Services, Hosted PBX, SIP Trunks, and Combo Bundles.

---

2. Module Overview (Commercial & Business Value)

• Zero-Touch Sales Pipeline: Converts prospects into paying, connected voice subscribers in under 2 minutes through automated digital onboarding.
• Flexible Elastic Sizing: Allows corporate clients to right-size their telephony spend by choosing exact extension bundles and voice channel capacity.
• Hardware & Hardware-as-a-Service (HaaS) Monetization: Supports leasing IP deskphones (e.g., Yealink T46U) bundled into monthly subscription invoices.
• Predictable Recurring Cash Flow: Plans automatically renew on monthly or yearly schedules, with recurring charges deducted directly from prepaid digital wallets or authorized credit cards.

---

3. 🎯 User Roles & Key Capabilities

User Role	Primary Objectives	Key Capabilities in Plan Store
New Customer / Onboarding Client	Evaluates voice service tiers and activates corporate telephony.	Browses catalog, compares feature sets, selects custom capacities, and completes initial subscription setup.
Enterprise Account Owner	Expands communications capacity for growing branch offices.	Provisions additional Hosted PBX domains, increases SIP trunk concurrency, and orders supplementary hardware rentals.
Product & Commercial Manager	Designs and publishes market-competitive telephony tiers.	Configures base prices, extension step ratios, included minutes, and promotional badges via the Admin Catalog view.
Billing Specialist	Ensures accurate invoicing and automated renewal cycles.	Verifies that catalog activations trigger automated pro-rated billing entries and digital wallet debits.

---

4. Plan Catalog & Multi-Tier Filter Navigation

The Plan Store interface provides a clean, responsive procurement grid with interactive search and category filtering chips.

Catalog Navigation Components

• Category Filter Chips:
  • All Services (5): Full view across all published voice, trunking, and hardware tiers.
  • Hosted PBX (2): Cloud-hosted multi-tenant PBX systems with virtual extensions, IVR, voicemail, and ring groups.
  • SIP Trunk (1): High-capacity wholesale voice trunking for on-premise IP-PBXs.
  • Combo Bundle (1): Unified solutions pairing cloud PBX instances with dedicated PSTN minute pools and hardware deskphones.
• Service Badges: Color-coded badges indicating service architecture: HOSTED PBX (green), SIP TRUNK (blue), COMBO BUNDLE (purple), and ELASTIC SIZING (cyan).
• Live Search Bar: Instant filtering by plan title, SKU code (PBX_PRO_10EXT, SIP_TRK_20CH), or descriptive capabilities.

---

5. Elastic Sizing & Interactive Checkout Modal

Clicking Configure Plan or Activate Plan launches the checkout modal, enabling immediate plan configuration and multi-engine provisioning.

Checkout Parameters & Sizing Controls

Parameter	Type	Description
Plan Selection	Display	Name of the plan being activated (e.g., Yealink T46U IP Deskphone Rental or Cloud Mini-PBX Business Pro).
Capacity Summary	Display	Included extensions (10 Extensions), concurrent channels (2 Channels), and cloud storage.
Monthly Service Total	Dynamic Price	Calculated recurring charge per billing period (e.g., $12.00 / MO or $39.99 / MO).
Domain Identifier	Input	Desired PBX subdomain realm (e.g., acme.ring2all.local) allocated upon creation.
Action Confirmation	Button	Activate & Provision Service triggers the backend provisioning handshake and creates the billing subscription.

---

6. Instant Tenant Domain & SIP Trunk Provisioning Handshake

When a client activates a plan from the Plan Store:

1. Anti-Fraud & Balance Verification:
   • For prepaid accounts, the system verifies sufficient wallet balance to cover the first billing cycle.
2. PBX Multi-Tenant Realm Creation:
   • Allocates a dedicated PostgreSQL domain record in ring2all_pbx with the specified extension and queue limits.
3. Sofia Profile SIP Directory Sync:
   • Generates dynamic Sofia profile XML bindings so that extensions registered under @domain.ring2all.local are instantly recognized by Telephony Server.
4. Perimeter SBC Route Injection:
   • Registers client trunk credentials with Kamailio’s drouting and dispatcher tables, enforcing concurrent call limits based on contracted channels.
5. Subscription Ledger Insertion:
   • Creates an active record in ss_billing.subscriptions with status = 'active', starting the automated recurring billing clock.

---

7. Troubleshooting & Verification

Checking Catalog Items in PostgreSQL

SELECT
    id,
    name,
    code,
    service_type,
    price,
    currency,
    billing_period,
    is_custom_sizing,
    included_extensions,
    included_channels,
    included_minutes,
    is_active
FROM plans
WHERE is_active = TRUE
ORDER BY price ASC;

Validating Catalog API Endpoint

curl -k -s -X GET "https://192.168.10.29/api/client/plans/catalog" \
  -H "Authorization: Bearer <CUSTOMER_JWT_TOKEN>" | jq .

---

8. Glossary

• Elastic Sizing: A dynamic billing model allowing clients to expand extensions and channel quotas in discrete step units with automatic price recalculation.
• Hosted PBX: A cloud-based private branch exchange system providing virtual call center and telephony capabilities without on-site hardware.
• SIP Trunk: A virtual voice pipe running over IP connecting an external PBX or VoIP system to the public switched telephone network (PSTN).
• Sofia Profile: The SIP signaling and media engine module in Telephony Server responsible for SIP registration, authentication, and RTP proxying.
• Provisioning Handshake: Automated inter-service communication protocol creating user accounts, routing rules, and credentials across multiple telecom subsystems.