From Fedora Project Wiki
Line 19: Line 19:
It also contains a strong logic-less templating engine called blade which support layouts and sections (to ensue code reusability).
It also contains a strong logic-less templating engine called blade which support layouts and sections (to ensue code reusability).


==== Why Laravel? ====
* [http://opensource.org/licenses/MIT MIT licence] which is [http://www.gnu.org/licenses/license-list.html#Expat GPL] compatible.  
* [http://opensource.org/licenses/MIT MIT licence] which is [http://www.gnu.org/licenses/license-list.html#Expat GPL] compatible.  
* Strong Community
* Strong Community

Revision as of 15:53, 3 May 2013

System Overview

There is a need of an information system where it can be used with in the project to track and analyse the finacial activities for FAms (Fedora Ambassadors), Managing Fund Requests, Receipts, Budget Proposals and generating reports.

Initial Given Scenarios

  • At the start of the year Budget owner set limits to regions (NA,EMEA,LATAM,APAC)
  • FAm make a fund request.
  • Once approved budget owner should approve the request and then deduct the amount from the allocated budget.
  • Once the FAm submit the receipts it should be forwarded to the Ledger(assume this is like updating a table for now).
  • At the end of the year FAm can submit their next year budget requirements to the system.
  • Budget owner can see those budget proposals and able to query them for region, amount, types and so on.

Frameworks & Tools

PHP Framework

The project will be developed using php and Laravel 4 (In beta but can be used for production), Laravel 4 is a framework for web artisans, applies the Model View Control (MVC) architecture/design pattern. Laravel contains a very strong database Object Relationship Mapper (ORM) called Eloquent (ActiveRecord Implementation) which will help us with our complex relations.

Laravel 4 also implements restful controllers / Resource Controllers and restful routes pattern in core.

It also contains a strong logic-less templating engine called blade which support layouts and sections (to ensue code reusability).

Why Laravel?

  • MIT licence which is GPL compatible.
  • Strong Community
  • MVC Framework
  • Composer Friendly. Can get multiple packages from Packagist.
  • Strong ORM, Called Eloquent.
  • Database Migrations. Simple Version control for Database Structure.
  • Come in handy with a built in CSRF protection.
  • Can force HTTPS on all routes or specific routes.
  • RESTful ready, Helps creating RESTful controllers, routes, resources.
  • JSON packed in, can return JSON, and auto detect requests types (If JSON will auto parse it, If normal form submissions will deal with it normally to capture the inputs)
  • Backed by many Symphony2 components.
  • All components are Unit Tested.

Note: I can't list all laravel features, I am only listing the features that will help us in our system.

UI Framework

I am planning to use Twitter Bootstrap v3 (Still in development but the milestone is near to the end), It should be launched before GSOC13 coding period starts.

The Twitter Bootstrap library will be themed in an external CSS file (To ensure that we will get regular bug fixes and don't break our theme), I will theme all the UI elements to make the project looks unique and match Fedora's branding guideline, Will try to keep the design Flat as much as possible (less shadows).

Twitter Bootstrap also plays well with Laravel in pagination and other elements.

Version Control & Issues Tracking

I will be using Git and Github, I will push code updates regularly, and I will use the GitHub issue tracker to track bugs and feature requests. At the end of the project we can migrate it to fedora's git repos.

Database

Data Models

  • Region: Responsible on each region (NA,EMEA,LATAM,APAC).
  • FundRequests: Handles the fund request by FAm details.
  • Receipts: Represents each receipt and related it to it’s FundRequest.
  • User Role
  • Account
  • Journal
  • PostingEntry
  • FinancialYear (Optional, We don't needed but it's availability may ease some report generation and keep the data models organized)
  • BudgetProposals: Represents Budget Proposal by FAm at the start of each year.
  • ProposalItems: Represent each item in the BudgetProposal. (Need more clarifications on type of items and needed information)

An old detailed database structure with relations and tables can be found here.

Access Control

FAS authentication

The Fedora Account System keeps track of Fedora Project contributors and the projects they work on. It is used to grant authentication and authorization to various components. FAS will be implemented in our system to authenticate users by OpenID.

Process:

  • User ask the system to authenticate
  • FAS will authenticate the user
  • FAS will send the username or unique user id.
  • Username or unique user id will be saved in a table with the corresponding role_id
  • When the user perform an action the system will check the corresponding role id if that role is permitted with Permission to do the action.

Suggestion: I am not sure that FAS support groups, If it support groups and the api allows to query the authenticated user groups, I suggest creating two groups in FAS one for the Budget owners and one for the FAm (Maybe both are already created), and instead of doing the role assignment inside out system, It happens inside FAS.

Roles

We will create roles to be able to determine if that user have the right permission to perform a specific action. (Creating additional Roles will not be a burden, Because the system check permissions not roles, we can create new roles and assign them with a set of pre implemented permissions anytime).

Basic Roles:

  • Adminstrator
  • FAmSCo members
  • Budget Owner
  • FAm

Permissions

Permissions is a set of actions which maybe shared by one or more Role(s). In the system we are going to check the user permission before making any action, If the logged in user role has the needed permission to perfore the action It will be performed otherwise he/she will be prompt by an error message e.g ("Access Denied") or we can throw an exception.

Example of permissions:

  • view_budget
  • allocate_budget
  • view_fund_request
  • create_fund_request
  • approve_fund_request

Determining all the Permissions now is a hard job, I will maintain a list of permissions and explanation for each one in a wiki page while implementing the project.

Double Entry System

In a ‘double entry’ system each value is stored twice, once as a credit, once as a debit. More info about double entry system with relational database here.

Rules to consider when making a double entry:

  • Every entry into the system must balance – i.e. the sum of any transaction must be zero.
  • The sum of all the values in the system at any one time must be zero (the ‘trial balance’).
  • No values can ever be amended or deleted. They must be negated with an opposing entry (a ‘contra’) and re-entered (‘re-booked’).

Transaction Types

There will be two types of transactions in our system.

  • Deposit: Will be used when the Budget Owner allocates budget.
  • Withdrawal/Payment: Will be used when the FAm attach the receipt to an approved Fund Request, to create the needed journal entries.

Accounts

Basic Accounts to be used in any journal entry, Account will increase as the system expand, as a start we will track the following accounts:

  • Cash Books: To track the cash in/out flow to the system
  • Allocated Budget: To track the decreases and increases for each region allocated budget.
  • Region Expense: To track the expenses for each region.

Note: Each region will have two accounts (Allocated Budget and Region Expense) and after any transaction related to a region the system will auto update the account_balance after doing some logic described below in the Journal Section. So we will always have the account balances to query about when generating reports.

The account table will save the following:

  • account_id
  • account_name
  • account_balance (Final balance of the account).

Journal

Journal is a representation for both debit and credit side of any transaction (Check Posting Below), Here we will save a unique sequential id for the journal, Transaction Type, User and Region, When creating a new journal the system will auto create two entries in the Posting table one for the debit and the other for the credit each with the amount and accounting period. Then the system will get the amount of each posting entry, corresponding amount and check the posting type against the account nature and if the credit means subtracting from account the posting amount will be subtracted from the current account balance to save the final balance for easy report generation on accounts and vise versa.

Account Nature Definition: More details here or here.

  • Cash -> Assets (Debit = Increase, Credit = Decrease)
  • Allocated Budget -> Income Account (Debit = Decrease, Credit = Increase) HEADS UP! TODO: Check if allocated budget is an Income Account or Owner Equity account.
  • Region Expense -> Expenses (Debit = Increase, Credit = Decrease)

Note: The system should verify that every journal entry created have two corresponding posting entries, to ensure that the accounting rule is applied.

Posting

Posting is where the actual amounts are saved whether to the debit side or the credit side, we will generate a unique id for each entry then save:

  • journal id: The corresponding journal id from the above.
  • account: The corresponding account e.g (cash books, allocated budget, region expense).
  • posting type: Debit (dr) or Credit (cr).
  • amount: The absoute value of the transaction amount.

Note:

  • The balance of the Posting Amount column always being zero after every complete Journal transaction.
  • System must not allow an incomplete one (debit without credit or vise versa).

Examples & Scenarios

Example Scenario 1:

  • Budget Owner "Tom" allocate $500 for region "EMEA". Deposite transaction.
  • In normal paper double entry accounting system the allocated budget account will be credited by $500, and the Cash Book account will be debited by $500 to match.
  • The system create a new Journal entry which will save Deposit as transaction type, "Tom's" user id, region "EMEA" id.
  • The system will aslo create two entries in the Posting table.
    • 1st Entry: Journal Transaction Id, Region "EMEA" Account (Allocated Budget) id, amount = 500, posting type = cr.
    • 2nd Entry: Same Journal Transaction Id, Account (Cash Book) Id, amount = 500, posting type = dr.
  • The system will also check Allocated Budget account nature in our case is (Income Account or Owner Equity) and will do an addition to the account balance in the accounts table to the original value there. (500 + Old Account Balance). (That way we will always have an updated account balance to query about for report generation).

Example Scenario 2:

  • FAm "John" submitted a receipt related to a previously approved fund request with a value of $100, He is in "EMEA" region and want to get paid. Withdrawal Transaction.
  • In normal paper double entry accounting system we will create one journal entry.
    • "EMEA" Region Expense account will be debited by $100 and the Cash Books will be credited by $100
  • The system will create a new Journal entry which will save Withdraw as transaction type, "John's" user id, region "EMEA" id.
  • The system will also create two entries in the Posting table.
    • 1st Entry: Journal Transaction Id, ("EMEA" Region Expense account) id, amount = 100, posting type = dr.
    • 2nd Entry: Journal Transaction Id, (Cash Books account) id, amount = 100, posting type = cr
  • The system will also check "EMEA" Region Expense account nature in our case is (Expense) and will do a subtraction to the account balance in the accounts table to the original value there. (100 - Old Account Balance) (That way we will always have an updated account balance to query about for report generation).

Report Generation

The below are just basic ideas of reports generation, I want to give the system administrators with some pre-set, simple and flexible ready reports which depends on their use case. Any other reports can be implemented later as long as the data are well structured which what I am giving a higher priority, I am not going to provide a financial reports generation tool, Instead I will provide the most needed reports and make it easy for end-users to get the required data with just a few clicks.

Kindly, Suggest any other needed reports.

Fund Requests Reports

Query Fund requests by Region, Status, Value and Financial Year.

Regions Ledger Report

  • Query by Region and Financial Year.
  • Shows Allocated Budget
  • Shows Remaining Budget
  • Shows Total of claimed Fund Requests

Budget Proposals Reports

Query all budget proposals by some attributes:

  • Type
  • Items
  • Region
  • Total Value
  • Other Attributes if Available.

FAms by Fund Requests Reports

Query all FAms with Fund Requests