Merge branch 'release/v0.2.0'

Author: BenMaruchu

README.md

@@ -1,33 +1,33 @@
-# Majifix
+# MajiFix
 
 MajiFix was developed by the World Bank in Tanzania to solve the challenge of tracking problems in cities through citizen crowd sourcing.
 
 MajiFix builds up on the movement of civic issue tracking by adopting since day zero the well known standard Open311 GeoReport v2.
 
 MajiFix is completely open source. It is free to use and to adapt, or adopt by anyone.
 
-## Our aim
+This is an official documentation on how you can contribute, use , extend or deploy
+MajiFix to your organization.
 
-With MajiFix, we aim to:
+## Contributing
 
-Open city governments, by creating new communication channels with their citizens.
-allow citizens to report problems they face in their daily lives, and empowering them to share existing problems.
-support public service providers in solving each and every problem, while giving feedback to people about updates on the efforts to solve each problem.
+Please improve this documentation by cloning this repo. Create a feature branch for what
+you are working on, after you are done, please submit your pull request.
 
-## Majifix components
+```sh
+git clone https://github.com/CodeTanzania/majifix-docs.git
+```
 
-MajiFix has different components
+Install all required dependencies
 
-- A ticket management system to support public officials to keep track of problems that were reported.
-- A management app that provides statistics about system performance to city managers.
-- A mobile app that citizens can use to easily report problems.
-- A Facebook Messenger Bot, so that people can submit problems through FB Messenger’s interface. No need to download an app.
-- A USSD interface, specially relevant in places where not everyone owns a smartphone.
-- A public website, that publicly shows what is going on with the system.
+```sh
+npm install
+```
 
-## Our vision
+### Run it in development mode
 
-MajiFix tries to achieve two main outcomes:
+```sh
+npm run serve
+```
 
-- Improving efficiency of public services, by providing relevant information to the relevant stakeholders,at the right time.
-- Improving social accountability about public services, by providing public statistics about the performance of public services.
+and view it on http://localhost:3000

_media/background-image.jpg

@@ -2,15 +2,17 @@
 
 - Home
 
-  - [Introduction](/)
+  - [Introduction](/get-started.md)
 
 - Get Started
 
   - [Create Module](get-started/create-module.md)
+  - [Deploy MajiFix](get-started/deploy-platform.md)
 
 - Guides
 
   - [Best Practices](guides/best-practices.md)
+  - [Documentation](guides/documentation.md)
   - [Testing](guides/testing.md)
   - [Source Code Management](guides/scm.md)
 

_sidebar.md

@@ -0,0 +1,7 @@
+# Welcome to MajiFix
+
+[GitHub](https://github.com/CodeTanzania)
+[Get Started](/get-started)
+
+<!-- background image -->
+![](_media/background-image.jpg)

cover.md

@@ -1 +1,68 @@
-# Get Started on Majifix
+# MajiFix
+
+MajiFix was developed by the World Bank in Tanzania to solve the challenge of tracking problems in cities through citizen crowd sourcing.
+
+MajiFix builds up on the movement of civic issue tracking by adopting since day zero the well known standard Open311 GeoReport v2.
+
+MajiFix is completely open source. It is free to use and to adapt, or adopt by anyone.
+
+## Our aim
+
+With MajiFix, we aim to:
+
+Open city governments, by creating new communication channels with their citizens.
+allow citizens to report problems they face in their daily lives, and empowering them to share existing problems.
+support public service providers in solving each and every problem, while giving feedback to people about updates on the efforts to solve each problem.
+
+## MajiFix components
+
+MajiFix has different components. The following text provides brief description of each component.
+
+### MajiFix API
+
+MajiFix API is built on Node.JS. It is a RESTful API layer designed in support of reporting and tracking common public service (i.e. water) problems.
+
+It is consists of a suite of node packages covering the business/domain logic (the part of a platform that encodes the real-world business rules that determine how data is created, displayed, stored and changed), built for performance and scale.
+
+You can consider it as the data layer within a platform (including the data model). It is designed to be plugged into a templating layer, a mobile application or to be used with any other data consumer.
+
+MajiFix API provides a starting point that's further advanced than a framework. It allows you to get a complete data layer up and running in minutes.
+
+See source code [repository](https://github.com/CodeTanzania/open311-api).
+
+### MajiFix management app
+
+MajiFix management app is designed to help manages statistical information about system performance to official city managers.
+
+See source code [repository](https://github.com/CodeTanzania/open311-mobile-manager).
+
+### MajiFix citizen mobile app
+
+MajiFix mobile app is used by citizens to help them instantly report problems to city managers.
+
+Work still continues in a private repository. A public repository will be available as soon as a stable release is published.
+
+### MajiFix facebook messenger bot
+
+MajiFix facebook messenger bot is designed to create more social engagement by allowing citizens to submit problems to the MajiFix platform through Facebook Messenger's interface without downloading the actual app.
+
+See source code [repository](https://github.com/CodeTanzania/facebook-majifix-bot).
+
+### MajiFix USSD
+
+MajiFix USSD interface, specially relevant in places where not everyone owns a smartphone.
+
+See source code *This is yet to be published*.
+
+### MajiFix website
+
+A public website, that publicly shows what is going on with the system.
+
+See source code [repository](https://github.com/CodeTanzania/majifix.io).
+
+## Our vision
+
+MajiFix tries to achieve two main outcomes:
+
+- Improving efficiency of public services, by providing relevant information to the relevant stakeholders,at the right time.
+- Improving social accountability about public services, by providing public statistics about the performance of public services.

get-started.md

@@ -1,6 +1,6 @@
-# Create Majifix Module
+# Create MajiFix Module
 
-To create a new Majifix module follow these steps
+To create a new MajiFix module follow these steps
 
 - Clone this [repository](https://github.com/CodeTanzania/majifix-module-starter)
 - Delete .git folder by running

get-started/create-module.md

@@ -0,0 +1 @@
+# Deploy MajiFix Checklist

get-started/deploy-platform.md

@@ -5,7 +5,7 @@
 The most preferred editor used currently in the project is [Visual Studio Code](https://code.visualstudio.com/). If you opt to use this editor we advice you
 have these extensions installed in your editor.
 
-- jshint
+- Jshint
 - EditorConfig for VSCode
 - ESLint
 - Sublime Babel

guides/best-practices.md

@@ -0,0 +1,208 @@
+# Documentation
+
+In this project we try our level best to document the code so that the any new
+developer can easily chip in and understand what is going on. We highly recommend
+that you document any piece of code your are adding on this project.
+
+Below is our recommendation when documenting routers in API modules. It is not
+an exhaustive list but it will act as a starting point when we are documenting
+routers for API modules.
+
+## API Router Documentation
+
+For API routes documentation we use [apidoc](http://apidocjs.com/) which generate
+API documentation directly from block comments from the codes.
+
+### Route Documentation
+
+While documenting a route we recommend the comments to have the following
+
+- @api
+- @apiVersion
+- @apiName
+- @apiGroup
+- @apiDescription
+- @apiUse RequestHeaders
+- @apiUse [*Success returned object format*]
+- @apiUse RequestHeadersExample
+- @apiUse [*Success response example*]
+- @apiUse JWTError
+- @apiUse JWTErrorExample
+- @apiUse AuthorizationHeaderError
+- @apiUse AuthorizationHeaderErrorExample
+
+```js
+/**
+ * @api {get} /jurisdictions List Jurisdictions
+ * @apiVersion 1.0.0
+ * @apiName GetJurisdictions
+ * @apiGroup Jurisdiction
+ * @apiDescription Returns a list of jurisdictions
+ * @apiUse RequestHeaders
+ * @apiUse Jurisdictions
+ *
+ * @apiUse RequestHeadersExample
+ * @apiUse JurisdictionsSuccessResponse
+ * @apiUse JWTError
+ * @apiUse JWTErrorExample
+ * @apiUse AuthorizationHeaderError
+ * @apiUse AuthorizationHeaderErrorExample
+ */
+router.get(PATH_LIST, function getJurisdictions(request, response, next) {
+  ...
+}
+```
+
+For RequestHeaders, RequestHeadersExample, JWTError, JWTErrorExample,
+AuthorizationHeaderError and AuthorizationHeaderErrorExample apidocs comments are
+already defined in [majifix-common](https://github.com/CodeTanzania/majifix-common) module.
+To use it you just have to include it in your apidoc build system.
+
+This is an example of configuring apidoc grunt plugin to read apidoc comments from
+[majifix-common](https://github.com/CodeTanzania/majifix-common)
+
+```js
+apidoc: {
+    api: {
+        src: ['node_modules/@codetanzania/majifix-common/lib', 'lib/'],
+            dest: 'docs/',
+                options: {
+            debug: true,
+                includeFilters: ['.*\\.js$'],
+        }
+    }
+}
+```
+
+For Success returned object format and Success response example should be defined in the router file as shown in below examples:
+
+```js
+/**
+ * @apiDefine Jurisdictions
+ * @apiSuccess {Object[]} data List of jurisdictions
+ * @apiSuccess {String} data._id Unique jurisdiction identifier
+ * @apiSuccess {String} [data.jurisdiction = undefined] jurisdiction under
+ * which this jurisdiction belongs
+ * @apiSuccess {String} data.code Unique human readable coded name of
+ * the jurisdiction. Used in deriving service request code
+ * @apiSuccess {String} data.name Unique human readable name of the jurisdiction
+ * @apiSuccess {String} data.phone Primary mobile phone number used to
+ * contact jurisdiction
+ * @apiSuccess {String} data.email Primary email address used to contact
+ * jurisdiction direct
+ * @apiSuccess {String} [data.website] Primary website url of the jurisdiction
+ * @apiSuccess {String} [data.about] A brief summary about jurisdiction
+ * if available i.e additional details that clarify what a jurisdiction do
+ * @apiSuccess {String} [data.address] Human readable physical address of
+ * jurisdiction office
+ * @apiSuccess {String} [data.color] A color code(in hexadecimal format)
+ * eg. #363636 used to differentiate jurisdictions visually
+ * @apiSuccess {Point} [data.location] A center of jurisdiction. Its an
+ * office reachable by citizen(or customer)
+ * @apiSuccess {MultiPolygon} [data.boundaries] Jurisdiction boundaries.
+ * Its mainly used for geo lookup of service request jurisdiction
+ * based on its geo coordinates.
+ * @apiSuccess {Date} data.createdAt Date when jurisdiction was created
+ * @apiSuccess {Date} data.updatedAt Date when jurisdiction was last updated
+ * @apiSuccess {Number} total Total number of jurisdiction
+ * @apiSuccess {Number} size Number of jurisdiction returned
+ * @apiSuccess {Number} limit Query limit used
+ * @apiSuccess {Number} skip Query skip/offset used
+ * @apiSuccess {Number} page Page number
+ * @apiSuccess {Number} pages Total number of pages
+ * @apiSuccess {Date} lastModified Date and time at which latest jurisdiction
+ * was last modified
+ */
+
+
+/**
+ * @apiDefine JurisdictionsSuccessResponse
+ * @apiSuccessExample {json} Success-Response:
+ *  {
+ *    "data": [
+ *    {
+ *      "_id": "5aef42d59748e41e02e2a562",
+ *      "jurisdiction": {
+ *         "_id": "5af2aad4408ccb594b173f96",
+ *         "code": "84105193",
+ *         "name": "Faroe Islands"
+ *      },
+ *      "code": "66230485",
+ *      "name": "Kunze and Sons",
+ *      "phone": "1-964-200-3838 x5726",
+ *      "email": "mazie_bayer@hotmail.com",
+ *      "website": "vilma.net",
+ *      "about": "Molestias culpa porro pariatur.",
+ *      "address": "6552 Haven Prairie",
+ *      "color": "#b32acc",
+ *      "location": {
+ *         "type": "Point",
+ *         "coordinates": [
+ *           -77.5707764925392,
+ *           39.880937519031235
+ *         ]
+ *      },
+ *      "boundaries": {
+ *         "type": "MultiPolygon",
+ *         "coordinates": [
+ *         [
+ *            [
+ *              [
+ *                -76.80207859497996,
+ *                 55.69469494228919
+ *              ],
+ *              [
+ *                -75.71404588095427,
+ *                53.59198291229545
+ *              ],
+ *              [
+ *                -73.49941546156064,
+ *                47.7536674960849
+ *              ],
+ *              [
+ *                -78.24692848453104,
+ *                51.75424604090497
+ *              ],
+ *              [
+ *                -77.96718998971203,
+ *                43.532912808667284
+ *              ],
+ *              [
+ *                -80.05583147381611,
+ *                51.2655718114278
+ *              ],
+ *              [
+ *                -87.10717890417094,
+ *                49.55715210838287
+ *              ],
+ *              [
+ *                -86.82247323878836,
+ *                57.53161913076085
+ *              ],
+ *              [
+ *                -81.00322721012589,
+ *                56.68343367062641
+ *              ],
+ *              [
+ *                -81.15080039041881,
+ *                57.91444311426214
+ *              ],
+ *              [
+ *                -76.80207859497996,
+ *                55.69469494228919
+ *              ]
+ *             ]
+ *          ],
+ *        ]
+ *      }
+ *    ],
+ *    "total": 5,
+ *    "size": 1,
+ *    "limit": 1,
+ *    "skip": 0,
+ *    "page": 1,
+ *    "pages": 5,
+ *    "lastModified": "2018-05-06T18:00:53.283Z"
+ *  }
+ */
+```