adding readme on start coding

.github/CONTRIBUTING.md

@@ -33,3 +33,108 @@ This guide assumes a level of knowledge on how to use GitHub issues and pull req
 - Please keep your changes succinct in scope. Large pull requests with multiple changes to the codebase (i.e. multiple features) may be asked to be broken into multiple smaller pull requests.
 - Please give as much detail as is relevant about your approach to the solution in the pull request description.
 - When your code changes include any change to the visual UI, please include a screenshot of how your changes appear in the browser.
+
+## Start Coding
+
+This section is designed to help developers start coding in the project and understanding the basic concepts and components used.
+
+### Ember
+
+To understand the project you'll have to understand Ember, and it is advisable that you'll follow the tutorial: [Create your own app](https://guides.emberjs.com/v2.9.0/tutorial/ember-cli/) to get an understanding of how ember works and the basic folder structure.
+
+To read how Ember works in the following link: http://emberjs.com.
+
+### ES6
+
+Since the project is based on Ember, it uses ES6 standard for its client side code.
+
+### Folder structure
+
+The basic folder structure in **Ember** has the following folders and files
+
+| Folder Name | Purpose |
+| ----------- | ------- |
+| app/router.js | Defines routes and sub-routes in the application 
+| app/index.html | The basic index html of the system (this file should almost never be changed)
+| public/ | This directory contains assets such as images and fonts.
+| vendor/ | This directory is where front-end dependencies (such as JavaScript or CSS) that are not managed by Bower go.
+| dist/ | This folder is auto-generated by ember to contain all the project's compiled files and dependencies so that this folder can be copied as a stand-alone unit to be deployed on a server.
+| tmp | Ember CLI temporary files live here.
+| ember-cli-build.js | This file is an instruction on how to build the application
+
+In addition, these are description of some extra folder and files in use in this project:
+
+| Folder Name | Purpose |
+| ----------- | ------- |
+| server/ | This folder contains the basic definition for the application's backend
+| server/config.js | Basic configuration for the system, like CouchDB config, authentication etc.
+
+
+### Pod directories
+
+This project uses a folder structure called [Pods](http://cball.me/organize-your-ember-app-with-pods/) the is better suited for a large scale ember application.
+
+The Basic folder structure for Ember puts controllers, route and template in three different directories. The Pods approach organizes the folders in correlation to the application routes and keeps all three files in the same folder for each view. 
+
+### Extensions, Mixins & Abstracts
+
+This project has a massive usage of npm modules for ember, [ember mixins](http://emberjs.com/api/classes/Ember.Mixin.html) and abstracts.
+
+[ember-simple-auth](https://ember-simple-auth.com/) is an example of an ember npm module used in the project to enable authentication and authorization.
+
+`app/mixins/number-format.js` is a mixin that, when augmenting a class, adds functions to it for working with number. 
+
+`app/controllers/abstract-paged-controller.js` is an abstract that takes care of paging and displaying result.
+Using it is done like this:
+
+```js
+import AbstractEditController from 'hospitalrun/controllers/abstract-edit-controller';
+export default AbstractEditController.extend({
+...
+});
+```
+
+### Building the solution
+
+Once you run `script/server` or `ember serve` the project is build and run. Afterwards you can change the models, controllers and templates and ember will automatically update those file.
+
+You can use `ember build` to actively build a project or `ember build --environment=production` to build the project for production.
+
+### dist/ folder
+
+`dist/` is an automatically generated folder by ember that contains all the dependencies for the project to run. You can copy this folder as is to your server which is a simple way to deploy the project (There are other ways which are not mentioned here).
+
+### Ember data
+
+To make requests to the server the project utilizes [Ember data](http://emberjs.com/api/data/) and [REST Adapter](http://emberjs.com/api/data/classes/DS.RESTAdapter.html) to control requests between the client and the server.
+
+### Adapters
+
+Ember, by default uses http://jsonapi.org/ as a json convention. [CounchDB](http://couchdb.apache.org/) uses a different json convention. For that reason, an adapter (`app/adapters/application.js` which uses [ember-pouch](https://github.com/nolanlawson/ember-pouch)) was put between client to server communications to change server bound requests to CouchDB json format and client bound responses to [jsonapi](http://jsonapi.org) format.
+
+### Components in use
+
+[Ember components](http://emberjs.com/api/classes/Ember.Component.html) are reusable controls that you can integrate inside other pages\components.
+
+### Using Local Cache
+
+The database of **HospitalRun** uses [CouchDB](http://couchdb.apache.org/) to storage all of its data online.
+In parallel, it uses the offline feature of [PouchDB](https://pouchdb.com/) to store an offline copy of the database which syncs with the online instance on a different thread whenever the application is online.
+
+### Data Access Flow
+
+There are 3 database elements in play:
+
+1. Cloud based CouchDB
+2. Pouch DB Online for online requests
+3. Pouch DB Offline for synchronizing  data on a separate thread
+
+The application tries to access data via Pouch DB Online which tries to access data on the online Couch DB. If this request succeeds no more actions are required.
+As a failover mechanism, all outbound requests are monitored by pouch DB service so they can be redirected to the local offline pouch DB instance.
+
+The main reason for keeping two services of pouch DB on the client side is that keeping the Pouch DB on the main thread, causes the UI to run slowly whenever a sync is running.
+
+### Conflicts
+
+When there's a conflict in data, as long is the conflict occures between two different records or two different fields, the conflict resolution will be able to solve the conflict.
+If the conflict is between two versions of the same field, the later record value will apply.

README.md

@@ -128,6 +128,10 @@ Again, contributions are welcome via pull requests and issues.  Please see our [
 
 **Seriously, please read the [Contribution Guide](https://github.com/hospitalrun/hospitalrun-frontend/blob/master/.github/CONTRIBUTING.md).**
 
+## Start Coding
+To start coding and understand the frameworks, concepts and structure of the project, please read: 
+[Contribution Guide: Start Coding](.github/CONTRIBUTING.md#start-coding).
+
 ## Further Reading / Useful Links
 
 * [ember.js](http://emberjs.com/)