search

rodekruis / cash-program-design-wizard

The Cash Program Design Wizard tries to help Aid Workers who want to set up best practice Cash Programs for People Affected in multiple contexts.
Apache License 2.0
5 stars 2 forks source link
angular nestjs nodejs wizard

readme

Cash Program Design Wizard

The Cash Program Design Wizard tries to help Aid Workers who want to set up best practice Cash Programs for People Affected in multiple contexts.

Status

Latest releases and notable changes are in the CHANGELOG.

Preview of the latest (development) versions:

Stable, staging versions:

Latest test-runs:

Latest deployments:

Getting Started

Set up a local development-environment

Install client/server app/development dependencies

Run npm install from this directory. Or:

To finish you local set-up, run (required only once):

npm run prepare

To set-up running all relevant lint/test scripts with their related git actions.

Tests

Automated tests are configured and can be run with:

Mock/test Data

All initial database-contents are hard-coded in the server/src/seed-data-folder.

Program - program-demo.json

attribute type explanation
name string identifier of the program

Section - sections.json

attribute type explanation
name string identifier of the section (must be unique)
label translations-object what users see in the app
orderPriority number

Example:

{
  "name": "pa-info",
  "label": {
    "en": "The people we will help are mostly..."
  },
  "orderPriority": 1
}

Subsection - subsections.json

attribute type explanation
name string identifier of the subsection (must be unique)
orderPriority number
section string must match a name of a section

Example:

{
  "name": "pa-gender",
  "orderPriority": 1,
  "section": "pa-info"
},

Question - questions.json

attribute type explanation
name string identifier of the question (must be unique, used in the narrative report)
type string possible values: select-1, select-n, text, text-long, numeric
label {translations} what users see in the app
orderPriority number
subsection string must match a name of a subsection
tags [string] array of strings. possible values: cash, people, data. write it as: "cash", "data"
optionChoices [optionChoice] array of optionChoice objects, used only for types select-1 and select-n

Example:

{
  "name": "pa-gender-01",
  "type": "select-n",
  "label": {
    "en": "PA Gender"
  },
  "orderPriority": 1,
  "subsection": "pa-gender",
  "tags": ["people"],
  "optionChoices": [
    {
      "label": {
        "en": "Currently Unknown"
      },
      "name": "unknown",
      "orderPriority": 1
    },
    {
      "label": {
        "en": "Female"
      },
      "name": "female",
      "orderPriority": 2
    },
    {
      "label": {
        "en": "Male"
      },
      "name": "male",
      "orderPriority": 3
    },
    {
      "label": {
        "en": "Non Binary"
      },
      "name": "non-binary",
      "orderPriority": 4
    }
  ]
}

Hierarchy/Tree-structure

When these files are changed, a 'reset' of the database is required. This can be done via the endpoint: http://localhost:3001/scripts/reset

Local Development

After this initial set-up, you can start with:

The front-end client should be running at: http://localhost:4200/.
The back-end server should be running at: http://localhost:3001/api/.

Database migrations

During development the database-structure will change (e.g. an extra column in a table) while there is already data stored that cannot be lost. In this case we have to apply a migration.

Any time, the database-structure is adapted, before pushing, run:

npm run migration:generate <name>

This stores all edits in a migration-file, which should be committed and pushed along with your code changes. On test- and production-server, this file is automatically run by npm in the prestart stage.

To run this file manually, locally, do:

npm run migration:run

Recommended code-editor/IDE tools/extensions

Libraries in use in front-end/client app

Libraries/frameworks in use in the back-end/server API

Testing

During development, tests can be run continuously with:

To simulate a production-environment locally and be able to use all (offline) features, use:

npm run start:production --prefix client

Deployment(s)

For both the front- & back-end a shared configuration is used.

Prepare the correct configuration in the .env-file, based on the example: .env.example.
For more information, see: dotenv.

  cp .env.example .env

How to deploy the front-end/client app

The front-end/client app can be deployed as a static single-page-app or PWA.

How to deploy the back-end/server API

The back-end/server API can be deployed as a stand-alone Node.js web-app (connected to a database).

License

Released under the Apache 2.0 License. See LICENSE.