Python Object-Oriented Programming Data Architecture

Architecting a Telecom Billing Engine

A Python-based historical analytics system that parses chaotic JSON call records, enforces dynamic contract rules, and generates robust monthly billing cycles.

View GitHub Repository

The Problem: Scale & State

Telecom companies handle millions of event records daily. Analyzing historical data requires a system that can not only parse raw JSON structures but also maintain a strict internal "state" (remembering active contracts, calculating cross-month billing cycles, and applying complex rules accurately).

The goal of this project was to build exactly that: a highly testable, Object-Oriented engine capable of ingesting raw call data and outputting precise customer billing histories.

The Object Model

Customer: Manages personal data and tracks multiple associated Phone Lines.
Call & Event: Core units representing duration, timestamp, and routing data extracted from JSON.
Bill: A stateful object that accumulates free minutes vs. billed minutes across a 30-day window.

The Contract Engine

At the heart of the system is the Contract base class. By leveraging Polymorphism, the main application loop doesn't need to know how a contract works; it simply calls bill_call() and lets the subclass handle its specific business logic.

Term Contract

Requires a commitment duration. Offers a low monthly fee ($20) and low rates ($0.10/min), plus an allocation of free monthly minutes.

Edge Case: Canceling early results in the forfeiture of the initial deposit.

Month-to-Month

Maximum flexibility with no end date. Carries a much higher base fee ($50) and no free minutes, but allows penalty-free cancellation.

Logic: Pure transactional billing loop.

Prepaid

Operates entirely on credit balances. Features no monthly fees but actively tracks account balance against usage rates.

Edge Case: Includes an auto top-up threshold ($25 triggered if balance falls below $10).

Filtering & Spatial Visualization

Beyond billing, the system provides powerful analytical tools to query the dataset. I implemented filtering logic to isolate call events by customer, time period, or contract type. Furthermore, the system includes a visual component that maps these historical call connections spatially across a Toronto grid.

Key Engineering Takeaways

Polymorphism is Powerful: Implementing new_month() and cancel_contract() across three different subclasses kept the core processing loop incredibly clean. The main engine never needs `if/else` checks for contract types.
Test-Driven Reliability: Writing robust pytest unit tests was critical. Ensuring edge cases (like rolling over a Prepaid credit or exhausting Term free minutes midway through a call) were tested mathematically guaranteed system reliability.
JSON to Objects: Building the parser to map raw, unstructured dictionary data into strict Python class objects provided a strong foundation in modern data engineering workflows.