/**
@file
@brief  Developer documentation
@mainpage

Welcome to the developer documentation for the IntegralCES project.
This documentation is permanently under construction and we will
complete as is necessary to us.

@section about About

Integral CES is a suite of Drupal modules featuring social currencies
management for communities. See integralces.net
<http://www.integralces.net> for more documentation and
demo.integralces.net <http://demo.integralces.net> for a demonstration site.


@section alta_exchange Initializing an exchange group

Visit new exchange form <https://www.integralces.net/ces/bank/exchange/new>
and initialize the first exchange group. You must fill in the Administrator
section with the user that will be the exchange administrator (It cannot be
the current Drupal admin).

Visit admin exchanges page /ces/admin/ces , click
on the new exchange and activate it.  Login as exchange administrator and
write some welcoming blog posts.

#### Invite the users to create an account

Users can sign up and create a new account visiting
/user/register/exchange_name/ , where exchange_name is the short name of the
new exchange group (Four numbers or uppercase letters)

Publish some offers and wants, blog entries... And have fun!

@section modulo_raiz Base module CES

The root module is called ices. This module alone does not provide any feature
to the final user. It has a pair of objectives:

- It is a container for all other modules in a parent folder so ease the
  installation and upgrade.
- Provide some shared libraries to be used by any of the submodules.

The files that directly belong to the root module are include the mandatory
ces.info and ces.module and the shared libraries. Currently there is one shared
library. It consists on a database abstraction layer located in file
commons.db.logic.inc.


### Database

There is a common way to access Drupal database within all the CES sub-modules.
It is an approximate version of the active record pattern. The objective of
this layer is to concentrate all the database work in a single standardized
place. It isolates other code from the Drupal database layer and those it eases
bug detection, permits a centralized catching system and makes the adaptation
to Drupal API changes almost trivial. This common interface enterely defined in
the file commons.db.logic.inc. This file defines several classes:

- IcesDBObject: The abstract class that any persistent object must extend. For
  example, the class Exchange extends DBObject. For each class extending DBObject
  there is a table in the database. This class has a crucial property called
  table. A child class must set this variable to the table name associated with
  it. It also have default implementations for the two methods that convert the
  internal object variables into an associative array to be saved and vice-versa.
  By default object public properties will become table fields.  
      
- IcesSerializer: This class has methods to save, update, load and delete any
  object of type DBObject. It is the actual bridge with the Drupal database
  layer. Beyond the basic CRUD interface, it provides some other helper methods
  It also features a special serialization strategy for hierarchies of classes
  implementing the decorator pattern.  
  
- IcesLockSerializer: This is a subclass of Serializer for those operations that
  are delicate due to concurrency. This class assures that when you load an
  object, it won't be loaded by any other LockSerializer until you save it.  
  
- IcesDBTransaction: An empty wrapper for Drupal transaction.


![Base de datos](/../img/database.png)

@section modulo_ces_bank Module CES Bank

CES Bank is the main banking module. It defines and works with all
banking objects: exchange groups (exchages from now), accounts, transactions...

This module is divided in two parts:

- The bank API is the responsible of doing all the banking logic. It is
  located at the ces_bank.logic.inc. It has a public interface to create
  accounts, do transactions etc.  
  
- The bank module is properly the Drupal
  module with its .info and .module files and other files for pages and
  forms. It uses the bank API to perform the actions ordered from the web
  user interface.

#### IntegralCES Bank API

The Bank API contains all the logic of account management. It is organized in a
set of classes. There is only one public class that acts at the same time as a
controller for the whole set and as the public interface. All other classes are
private and should not be used from outside the file. Even the public
parameters of Bank class aren't of any of the other those class types. 

Bank API should be thought as an external library. In particular, it is independent of Drupal. By the way it could be used in integrations within other platforms. It uses the database access functions from the CES root module and it uses the messaging features from the CES notify module. Below is discussed the principal classes and their properties.

- CesBank: Public interface for all features provided for this API. The
  parameters and the return values of this class are, when structured data is
  needed, associative arrays. The work is deferred to the concrete private
  objects. A typical function implementation in this class is to receive and
  (minimally) parse the input, create the appropiate private object, call
  this object's correct function, (minimally) parse the result, and return
  it to the caller.
    
- CesBankExchange: Represents an exchange group of trade. It has a name, a
  4-letter code, and some configurable options.

- CesBankAccount: It is an interface representing a banking account. Currently
  there is only one implementation of this interface. It is expected for the
  future to use this interface also for remote hosted accounts.  
    
- CesBankLocalAccount: Implementation of Account for accounts stored in local
  database. An account belongs to a particular exchange. Every one has a
  unique identifier, started with the 4-letter code of its exchange followed
  by 4 numbers. Special accounts can end with 4 letters instead of numbers.
  Every LocalAccount is potentially related to one or more users, and every
  user can have one or more accounts of this type. Each account has also a
  LimitChain, which determines the credit and debit (and other) limits for
  this particular account.
    
- CesBankAccountLimit: Atomic abstract limit for an account. It is the
  building block for LimitChains.
    
    - AbsoluteDebitLimit: Limits the total debit of an account.
    
    - AbsoluteCreditLimit: Limits the total credit of an account.
    
- CesBankLimitChain: An ordered set of AccountLimit, identified with a name.
  Every account has a link to an object of this type. An account satisfies a
  CesBankLimitChain: if it satisfies all its AccountLimits. An exchange can
  configure several LimitChains for several types of accounts. For example,
  one 'default' for new members, one 'organization' for shared accounts that
  need more flexibility and one 'public' for public accounts without any
  limit.  
  
- CesBankTransactionInterface: Interface for the transaction between two
  accounts. It has methods for accessing both account codes, the amount and the
  description or concept of the transaction. Several implementations exist
  using a decorator pattern scheme.  
    
- CesBankBasicTransaction: Transaction between two accounts of the same
  exchange.  
    
- CesBankDecoratedTransaction: Abstract transaction which delegates all
  methods to a 'parent' transaction that contains as a property. This class
  can be inherited to add functions to a transaction.
  
- CesBankInterexchangeTransaction: Child of DecoratedTransaction to allow
  trading between accounts of distinct exchanges. (Still in development)

### Transaction lifecycle  

Transactions have only two operations: apply a new transaction and revoke a
previously applied one. However, a transaction will go through several states
between the creation and the effective and irreversible application. This
lifecycle is summarized in the diagram below that will now be described state
by state.

- NEW: Initial state. The transaction has been created but hasn't already
  been triggered to apply. This is the state while the transaction can be
  edited. Waiting for the user to apply this transaction.  
  
- TRIGGERED: The transaction has been triggered to be applied. Immediately
  after it asks acceptance from all pertinent authorities. It is waiting for
  their response. It will become ACCEPTED or REJECTED.  
  
- ACCEPTED: The transaction has been accepted by all authorities. It is being
  effectively applied by the system. This state is very short-lived in local
  transactions. The following state will be COMMITTED or ERROR if system
  fails to apply the transaction -for instance, a remote server couldn't
  respond.  
  
- COMMITTED: The transaction is successfully applied. It can however be
  revoked. If there aren't issues for this transaction after a prudencial
  time, it will be archived.  
  
- ARCHIVED: The transaction is archived and successfully applied.  Nothing
  can be done with it. It exists only as historical data.  
  
- REJECTED:  The transaction -previously triggered to be applied- has been
  rejected by some of the authorities. It will be discarded after a
  prudential time. It can sill become ACCEPTED if some authorities rectify.  
  
- DISCARDED: The transaction is discarded and has not been applied. Nothing
  can be done with it. It exists only as historical data.  
  
- ERROR: Some system error occurred while applying or revoking the
  transaction. The administrator should take care of it.

These were the distinct states a transaction may pass through while being
applied. The following are those states related with the revoke operation. The
starting state of the revoke operation is the COMMITTED state.

- REVOKE TRIGGERED: The transaction has been triggered to be revoked. Waiting
  for acceptance of this operation by all authorities.  

- REVOKE ACCEPTED: The revoke operation has been accepted by all
  authorities. The system is effectively revoking the transaction. This
  state is very short-lived state in local transactions. The following
  state will be REVOKED or ERROR if system fails to revoke the transaction.  

- REVOKE REJECTED: Some authorities did not accept the revoke operation.
  The transaction will remain applied and it will be ARCHIVED after a
  prudential time.

- REVOKED: The transaction has been successfully revoked. It will become
  DISCARDED after a prudential time.

The transaction state is changed using the setState() function of the
Transaction interface. This function also triggers the appropriate actions. For
instance, when the state is changed from TRIGGERED to ACCEPTED, it starts the
effective application of the transaction.

![Estados de las transacciones](/../img/states_transaction.png)

#### CES Bank module class diagram

Class diagram for the banking module. It is an approximation of the actual
implementation: there are many more properties and methods, and some of them
may have distinct names. However, the architectural essence is correct.

![Diagrama de clases](/../img/class_diagram.png)

### Other components of IntegralCES

- @subpage install
- @subpage dev_flow
- @subpage ces_permissions_doc
- @subpage external_transactions_doc
- @subpage translations_doc

*/
