cgrates/docs/intro.rst

Introduction
============
CGRateS is a very fast and easy scalable rating engine targeted especially for telecom providers.

It is written in go (http://golang.org) and accessible from any language via JSON RPC. The code is well documented (go doc compliant API docs) and heavily tested.

After testing various databases like Kyoto_ cabinet, Redis_ or Mongodb_, the project focused on Redis as it delivers the best trade-off between speed, configuration and scalability. However connection to any database can be easily integrated by writing a simple adapter.

.. _kyoto: http://fallabs.com/kyotocabinet
.. _Redis: http://redis.io
.. _Mongodb: http://www.mongodb.org

Here are some of the configurations in which CGRateS can operate:

.. image::  images/Simple.png
If the network does not require more than one rater to handle the calls. The balancer can be left out and the rater can be queried directly. In this case the rater must be started with -standalone=true and -freeswitch=true options.

.. image::  images/Normal.png
While the network grows more raters can be thrown into the stack to offer more requests per seconds workload. This implies the usage of the balancer to distribute the requests to the raters running on the different machines.

.. image::  images/Complicated.png
Of course more session managers can serve multiple call switches and all of them are connected to the same balancer. We are planning to support multiple balancers for huge networks if the need arises.


Features
--------
+ Rates for prepaid and for postpaid
+ The budget expressed in money and/or minutes (seconds)
+ High accuracy rating: configurable to milliseconds
+ Handles volume discount
+ Received calls bonus
+ Fully/Easy configurable 
+ Very fast (5000+ req/sec)
+ Good documentation ( that's me :)
+ Commercial support available

How does CGRateS work?
----------------------
Let's start with the most important function: finding the cost of a certain call. The call information comes to CGRateS as the following values: subject, destination, start time and end time. The engine will lookup in the database for the activation periods applicable to the received subject and destination. What are the activation periods?

The activation period is a structure describing different prices for a call on different intervals of time. This structure has an activation time, from this time on the activation period is in effect and one ore more (usually more than one) intervals with prices. An interval is looking like this:

::

	Interval {
		Months 
		MonthDays
		WeekDays
		StartTime, EndTime
		Weight, ConnectFee, Price, BillingUnit
	}

It specifies the Month, the MonthDay, the WeekDays and the StartTime and the EndTime when the Interval's Price is in effect. 

For example the interval {"Month": [1], "WeekDays":[1,2,3,4,5]. "StartTime":"18:00:00", "Price":0.1, "BillingUnit": 1} specifies that the Price for the first month of each year from Monday to Friday starting 18:00 is 0.1 cents per second. Most structure elements are optional and they can be combined in any way it makes sense. If an element is omitted it means it is zero ore any.

The ConnectFee specifies the connection price for the call if this interval is the first one from the call and the Weight will establishes which interval will set the price for a call segment if more then one applies to it. 

For example there is an interval defining price for the weekdays and another interval that defines a special holiday prices. As that holiday is also one of the regular weekdays than both intervals are applicable to a call made on that day so the interval with the smaller Weight will give the price for the call in question. If both intervals have the same Weight than the interval with the smaller price wins. It is, however, a good practice to set the Weight for the defined intervals. For more information see :ref:`data-importing`.

So when there is a need to define new sets of prices just define new ActivationPeriods with the StartTime set to the moment when they become active.

Let's get back to the engine. After it finds the applicable ActivationPeriod(s) it will split the call interval in multiple time-spans attaching the appropriate ActivationPeriod and Interval to each them. The final price will be the sum of the prices of these times spans plus the ConnectionFee from the first time-span of the call.

The other functions relay on a user budget structure to manage the different quotas for postpaid and prepaid clients. The UserBudget keeps track of user credit, free SMS and minutes for every destination, Internet traffic and offers the volume discount and received call bonus. Let's take them one by one.

CGRateS provide api for adding/substracting user's money credit. The prepaid and postpaid are uniformly treated except that the prepaid is checked to be alway greater than zero and the postpaid is always lower than zero.

Both prepaid and postpaid can have a limited number of free SMS and Internet traffic per month and this budget is replenished at regular intervals conforming to user tariff plan or as the user buys more free SMS (for example).

The free (or special price) minutes must be handled a little differently because usually they are grouped by specific destinations (e.g. national minutes, ore minutes in the same network). So they are grouped in buckets and when a call is made the engine checks all applicable buckets to consume minutes according to that call.

Another special feature allows user to get a better price as the call volume increases each month. This can be added on one ore more thresholds so the more he/she talks the cheaper the calls.

Finally bonuses can be reworded to users who received a certain volume of calls. For information on how to define the bonuses see :ref:`data-importing`.