Skip to content

CRM Business Flows

This document details the high-level business flows and architectural intersections coordinated by the crm2.micro.bss PHP frontend.

The CRM acts as an administrative proxy, managing its own local access controls (MariaDB) while deferring core telecommunication logic to the server.micro.bss C++ engine via strict gRPC endpoints.

1. Subscriber Management & Invoice Visualization

The subscriber lifecycle is the core entity managed by the CRM.

Subscriber Creation (subscriber-new.php)

New subscribers are provisioned through a strict validation pipeline to guarantee network integrity before insertion: 1. Resource Allocation: The UI queries the C++ backend for available unassigned network resources: - GetAvailableResources(MSISDN) - GetAvailableResources(IMSI) - GetAvailableResources(Handset) 2. Form Enforcement: The CSR must pair an available MSISDN, an identity (SSN), demographic information, and a valid C++ Price Plan ID. 3. Execution: The aggregated data is pushed via the CreateSubscriber gRPC call. The C++ engine handles the atomic database inserts for the subscriber and default balances.

Visualization & Dashboards (subscriber.php)

A subscriber's historical and real-time state is rendered across specific unified tabs: - Profile: Demographic and persistent payment data. Adjusts dynamically to show Balance for Prepaid and Bill-cycle for Postpaid users. - Reporting: - GetSubscriberUsage streams the last 3 months of raw Call Detail Records (CDRs) for dispute resolution. - GetSubscriberBills streams the monthly consolidated statements. - Invoice Rendering: PDF invoices generated asynchronously by the backend are served blindly through the api/download.php UI wrapper which fetches invoices/{year}/{month}/.../*.pdf from the internal filesystem.

2. CSR Self-Care (profile.php, mfa-setup.php)

Unlike subscribers, Customer Service Representatives (CSRs) and Administrators are managed exclusively within the local CRM MariaDB layer, ensuring the C++ charging engine is completely decoupled from UI authentication concerns.

  • Profile Management: CSRs can update their display metrics (Theme, Language, Email) which persist into local PHP $_SESSION caches for rendering speed.
  • Security & MFA: The lib/Auth.php layer enforces generic credential hashing alongside Time-Based One-Time Passwords (TOTP). CSRs can generate secure QR codes and bind Authenticator Apps to their physical csr_users row.

3. Administrative Domains

Global configurations are bifurcated between local UI preferences and immutable core charging logic.

CSR Fleet Management (admin/users.php)

Admin-tier users possess CRUD authority over the local csr_users table. They can forcibly create new agents, rotate passwords, or toggle login access dynamically (active boolean) without restarting the web service.

Price Plan Observability (admin/price-plans.php)

  • Read-Only Concept: The PHP interface does not create or define Price Plans.
  • Execution: The UI invokes GetRefData to pull the C++ RefData singleton (which contains REF_Price_plan, REF_Service, and REF_Billcycle). This serves as a read-only dictionary mapping IDs to display-friendly strings across the rest of the application.
  • (Roadmap: Full write management of Price Plans via gRPC is planned for a future release).

Taxation (admin/vat.php)

VAT configurations are stored in the local CRM database (vat_config). This allows the frontend to apply dynamic percentage-based visual surcharges to reports without altering the base rated prices computed by the C++ engine.

4. Voucher Lifecycle Activities

Voucher pins represent prepaid monetary injections. The backend tracks their cryptographic integrity, but the lifecycle state is managed via the CRM.

  • Listing & Oversight (admin/vouchers.php): Admins use SelectVouchers to query the inventory of pins. Vouchers exist in three states: NEW (1), USED (2), or ERROR (3).
  • Manual Overrides: The UI allows forcing a voucher out of circulation by updating its state (e.g., from NEW to ERROR if a batch was printed incorrectly) using api/vouchers/update.php.
  • Redemption (api/vouchers/redeem.php): A direct pipeline initiated from the subscriber.php profile. The UI sends the 16-character alphanumeric code to the backend via RedeemVoucher. If successful, the C++ engine atomically marks the pin USED and increments the active subscriber's real-time balance.

5. Billing Executions

The generation of formalized financial statements is managed asynchronously to prevent UI blocking.

Monthly Regular Billruns

  • The standard monthly billing engine (CDRLoader and BillFormatterHandler) is completely invisible to the CRM. The PHP interface simply consumes the final generated rows surfacing in the GetSubscriberBills endpoint.

On-Demand Billing (api/billing.php)

If a CSR needs to force an immediate calculation (e.g., a customer is terminating their contract mid-month): - The subscriber.php UI utilizes an asynchronous AJAX call pointing to the local PHP proxy API. - The wrapper invokes the strict ExecuteBilling gRPC command. - The C++ backend aggregates unbilled CDRs instantly, generates the PDF, and returns an ACK_OK. The UI responds by forcing a localized page reload, instantly exposing the new invoice row to the user.