prototype-app

Repository for putting prototype work from Thoughtworks HSP around building single page web app for Mifos X.

Overview Video

To get a good overview of the code layout, and recommendations going ahead on the Angular.js Prototype application, please watch this video recording of a session taken by Silvio from ThoughtWorks:

YouTube Video on MifosX UI Prootype Code Walkthrough

Online Demo

Access the online demo version here

Building from source

1. Note: Ensure you have npm installed - goto http://nodejs.org/download/ to downloand installer for your OS.

2. Clone this respository to your local filesystem

3. To download the dependencies, and be able to build, first install bower & grunt:

npm install -g bower
npm install -g grunt-cli

4. Next pull the runtime and build time dependencies by running bower and npm install on the project root folder:

bower install
npm install

Done.

Adding dependencies

You can also add more dependencies on bower.json. You can search for them in http://sindresorhus.com/bower-components/ or even:

bower search <package>

Running the tests

Just open test/SpecRunner.html in the browser.

Background

The Mifos project (http://www.mifos.org/about) was originally setup and guided by Grameen Foundation. It has been open source since inception but in recent years the community for open source microfinance (http://www.openmf.org) took over maintanance and future development of the Mifos project.

Whilst the community continues to maintain and support the original Mifos MIS project, most development has shifted to the Mifos X project.

Mifos X

Mifos X is a MIS platform for microfinance. Its capabilities are exposed through a RESTful API.

• Github Project Page: https://github.com/openMF/mifosx
• Reference App Project Page: https://github.com/openMF/mifosx-community-apps
• Online Demo Reference App: https://demo.openmf.org/ - log on using username/password of mifos/password
• Online Demo API Documentation: https://demo.openmf.org/api-docs/apiLive.htm
• Online Demo API (Example call): https://demo.openmf.org/mifosng-provider/api/v1/offices?tenantIdentifier=default&pretty=true - log on using username/password of mifos/password

Setting up Mifos X server

• Follow instructions at https://github.com/openMF/mifosx/wiki

Troubleshooting

In case you get 'PermGen - Out of space' errors when running the tomcatRunWar task, increase the memory of your java process through the GRADLE_OPTS env variable

export GRADLE_OPTS="-Xmx512m -XX:MaxPermSize=265m"  

Scope of Work

For the prototype the following scenarios should suffice:

1 Navigate to Role-based landing screen after login

This scenario will involve:

• provide login screen that will use platform authentication api (https://demo.openmf.org/api-docs/apiLive.htm#authentication)
• on failure handle error response from platform authentication api
• on success display appropriate screen based on the organisational role associated with authenticated user.

Existing users on demo server:

• mifos/passowrd has a 'Super user' role
• joejoe/password has a 'Branch Manager' role
• jackjack/password has a 'Funder' role

Authentication API response

{
  "username": "mifos",
  "userId": 1,
  "base64EncodedAuthenticationKey": "bWlmb3M6cGFzc3dvcmQ=",
  "authenticated": true,
  "staffId": 1, 
  "staffDisplayName": "Director, Program", 
  "organisationalRole": { 
     "id": 100, 
     "code": 
     "staffOrganisationalRoleType.programDirector", 
     "value": "Program Director" 
  },
  "roles": [
    {
      "id": 1,
      "name": "Super user",
      "description": "This role provides all application permissions."
    }
  ],
  "permissions": [
    "ALL_FUNCTIONS"
  ]
}

On each of the different landing screens for 'Super user', 'Branch Manager' and 'Funder' role it would suffice to just indicate that these are different screens through static content. If you wish you can invoke different platform API calls on each of the different landing pages e.g.

• 'Super user' -> show all offices through https://demo.openmf.org/api-docs/apiLive.htm#offices_list
• 'Branch Manager' -> show all clients through https://demo.openmf.org/api-docs/apiLive.htm#clients_list
• 'Funder' -> show all funds through https://demo.openmf.org/api-docs/apiLive.htm#funds_retrieve

2 CRUD screens around typical administrative area like users

Implement CRUD behaviour around the users resource (https://demo.openmf.org/api-docs/apiLive.htm#users)

Objective

Along with code to demostrate how the scenarios in scope of work can be implemented, the objective of this prototype/spike is to demonstrate a clean way of developing a single page app which exhibits the following qualities:

1. Structured Approach
2. Automation of dev code into production artifacts
3. Localisation and Internationalisation
4. Customisable and Extensible

Together with code to demostrate how the scenarios in scope of work are implemented