Call Detail Records (CDRs) & Usage Analytics Module Documentation

Module Code: billing/client/cdrs
Route: /portal/cdrs
Backend Service: clientService.ts (ring2all-billing-api)
Database Table: cdrs_rated
Brand Purity: 100% White-Label Compliant (Ring2All Billing)

Executive Summary & Commercial Transparency
Technical Architecture & Rating Pipeline
🎯 User Roles & Key Capabilities
Visual Interface & Screen Breakdown
Itemized CDR Metrics & Hangup Cause Analytics
RFC 4180 CSV Data Export Engine
Database Schema & Data Dictionary
Diagnostic CLI & Operational Playbooks
Domain Glossary

1. Executive Summary & Commercial Transparency

The Call Detail Records (CDRs) module empowers subscribers with complete, itemized visibility into every inbound and outbound telephone session handled across their PBX domains and wholesale SIP trunks.

+-------------------------------------------------------------------------------+
|                       COMMERCIAL & OPERATIONAL IMPACT                         |
+-------------------------------------------------------------------------------+
| • Dispute Elimination: Complete transparency regarding call timestamps,       |
|   destination rate tiers, billed seconds, and precise dollar costs.          |
| • Sub-Minute Telecom Billing: Verifies exact initial block and step rounding  |
|   rules applied to every completed destination.                               |
| • Granular Exporting: Instantly downloads raw records to CSV for integration  |
|   into enterprise ERPs, spreadsheets, and internal cost centers.              |
| • Multi-Tenant Data Isolation: All queries are strictly scoped by             |
|   authenticated customer ID at the SQL layer.                                 |
+-------------------------------------------------------------------------------+

2. Technical Architecture & Rating Pipeline

When an active call terminates on Telephony Server or Kamailio SBC, the Online Charging System (OCS) calculates destination pricing, applies rate card tiers, and commits the finalized record to cdrs_rated:

 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Telephony Termination Engine                      │
 │                      Telephony Server 1.11 / Kamailio 6.1                    │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │ CDR Event Hook
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │             Ring2All Online Charging System (OCS) Engine               │
 │             • Resolves Effective Customer Rate Card                    │
 │             • Calculates Initial Block (e.g. 30s) + Step (6s)          │
 │             • Computes: Cost = (BilledSeconds / 60) * RatePerMin       │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼ SQL INSERT
 ┌────────────────────────────────────────────────────────────────────────┐
 │                  PostgreSQL 17 Storage (public.cdrs_rated)             │
 │                  WHERE customer_id = $authCustomerId                  │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │ GET /api/client/cdrs
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │               Client Self-Care Portal UI (CdrsPage.tsx)                │
 │               Real-Time Live Search, Dispositions & CSV Exporter       │
 └────────────────────────────────────────────────────────────────────────┘

3. 🎯 User Roles & Key Capabilities

Access to CDR data is restricted strictly to authorized customer representatives:

User Role	Access Level	Primary Operational Capabilities
Enterprise Telecom Administrator	Full Audit	Searches all extension calls, verifies call completion rates, identifies anomalous calling spikes.
Corporate Controller / CFO	Financial Reconciliation	Audits itemized usage against monthly invoices and prepaid wallet debits; verifies rate card accuracy.
Call Center Operations Lead	Operational Analytics	Evaluates call durations, identifies failed or busy destinations, analyzes talk-time efficiency.
Compliance Officer	Audit & Legal	Exports unalterable call history logs with standardized UTC timestamps and international prefixes.

4. Visual Interface & Screen Breakdown

4.1 Real-Time CDR Data Grid Overview

The CDRs interface provides a clean, responsive layout optimized for high-volume record analysis:

Call Detail Records (CDRs) Analytics

Toolbar Controls: Dynamic destination/source search bar, instant refresh button, and one-click CSV export action.
Timestamp & Extension: Accurate local date/time display alongside the calling SIP extension or source CLI.
Destination Details: Destination number, resolved carrier country/region name, and dialed prefix.
Duration Metrics: Breakdown of physical connection duration (seconds) versus billable time (minutes).
Cost & Status: Calculated charge in USD with visual badges for Billed, Completed, or Failed.

5. Itemized CDR Metrics & Hangup Cause Analytics

The portal parses standard Q.850 / SIP termination codes into human-readable dispositions:

Hangup Cause Code	SIP Response Code	Portal Status Badge	Operational Meaning
`NORMAL_CLEARING`	`200 OK (BYE)`	`Completed` (Green)	Call ended cleanly by either calling or called party.
`USER_BUSY`	`486 Busy Here`	`Busy` (Amber)	Remote terminal was engaged in another call.
`NO_ANSWER`	`408 Request Timeout`	`No Answer` (Amber)	Remote endpoint rang until timeout without answering.
`ORIGINATOR_CANCEL`	`487 Request Terminated`	`Cancelled` (Gray)	Calling party hung up prior to call answer.
`CALL_REJECTED`	`603 Decline`	`Rejected` (Red)	Destination terminal explicitly declined incoming INVITE.

6. RFC 4180 CSV Data Export Engine

The client-side export generator compiles filtered records into standardized CSV format:

MIME Type: data:text/csv;charset=utf-8
Column Headers: Call Date, Source, Destination, Duration (sec), Billed (min), Cost ($), Status, Hangup Cause
Automatic Naming: cdrs_YYYY-MM-DD.csv for clean archiving.

7. Database Schema & Data Dictionary

Table: `public.cdrs_rated`

CREATE TABLE public.cdrs_rated (
    id                  BIGSERIAL PRIMARY KEY,
    uuid                UUID NOT NULL DEFAULT gen_random_uuid(),
    call_uuid           VARCHAR(64) NOT NULL UNIQUE,
    customer_id         BIGINT REFERENCES customers(id) ON DELETE SET NULL,
    sip_account_id      VARCHAR(100),
    source_number       VARCHAR(50) NOT NULL,
    destination_number  VARCHAR(50) NOT NULL,
    prefix              VARCHAR(32),
    destination_name    VARCHAR(255),
    duration_seconds    INTEGER NOT NULL,
    billed_seconds      INTEGER NOT NULL,
    rate_per_minute     NUMERIC(10,6) NOT NULL,
    connection_fee      NUMERIC(10,6) NOT NULL DEFAULT 0.000000,
    cost                NUMERIC(10,4) NOT NULL,
    call_start          TIMESTAMPTZ NOT NULL,
    call_end            TIMESTAMPTZ NOT NULL,
    hangup_cause        VARCHAR(50),
    status              VARCHAR(20) NOT NULL DEFAULT 'billed',
    carrier_name        VARCHAR(100),
    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- High-performance query index for customer portal
CREATE INDEX idx_cdrs_customer_time ON cdrs_rated (customer_id, call_start DESC);

8. Diagnostic CLI & Operational Playbooks

Query Customer CDRs via PostgreSQL

# Execute on Billing DB host
su - postgres -c "psql -d ss_billing -c \"
SELECT call_start, source_number, destination_number, destination_name,
       duration_seconds, billed_seconds, cost, status
FROM cdrs_rated
WHERE customer_id = 5
ORDER BY call_start DESC LIMIT 5;
\""

9. Domain Glossary

ASR (Answer-Seizure Ratio): Percentage of attempted calls that are successfully answered.
Billed Seconds: Total duration after applying initial connect blocks and billing increment steps.
CLI (Calling Line Identification): Originating caller ID transmitted during call setup.
OCS (Online Charging System): Engine responsible for real-time rating and credit control.