---
title: "Call Detail Records (CDRs) & Usage Analytics Module Documentation"
description: "Documentation for Call Records (CDRs)"
---

> **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)

---

## Table of Contents
1. [Executive Summary & Commercial Transparency](#1-executive-summary--commercial-transparency)
2. [Technical Architecture & Rating Pipeline](#2-technical-architecture--rating-pipeline)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Screen Breakdown](#4-visual-interface--screen-breakdown)
5. [Itemized CDR Metrics & Hangup Cause Analytics](#5-itemized-cdr-metrics--hangup-cause-analytics)
6. [RFC 4180 CSV Data Export Engine](#6-rfc-4180-csv-data-export-engine)
7. [Database Schema & Data Dictionary](#7-database-schema--data-dictionary)
8. [Diagnostic CLI & Operational Playbooks](#8-diagnostic-cli--operational-playbooks)
9. [Domain Glossary](#9-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](/screenshots/billing/client/cdrs/cdrs-list.png)

* **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`
```sql
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
```bash
# 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.