@hedviginsurance/embark

Embark

Embark is Hedvigs framework for creating forms and user stories.

Core concepts

1. Embark flow

Embark flows describe forms used to get users necessary data during the onboarding process. They consist on a number of steps (a.k.a passages) presented in a question/answer manner with transitions from one to another in a non linear way, meaning that the next step might depend on users previous answer. Embark flows are created with the assistence of a tool called Angel.

2. Embark Server

Embark Server is responsible to serve Embark flows so Embark Clients like web-onboarding and ios/android apps can access them.

3. Embark Client

An Embark Client is responsible to access and display Embark flows.

What's inside?

This repository holds three things:

• The implementation for the Embark Server. It simply consists on web server that exposes all the Embark Flows placed under angel-data folder. Its implementation can be found inside server.ts file.
• The implementation of the Embark Client for the web: Embark Client Web. It consists on a set of React components and hooks.
• A small React app used for previewing while developing Embark Flows with our custom tool: Angel. It's exposed via Embark Server under /client.js endpoint. More info about Angel can be found in its repository. For the content editor's documentation - see embark editor docs.

Getting Started

Prerequisites

• node
• yarn v1

Install Node with nvm

While one can install node by downloading it from their official website we recomend do it through nvm which is a tool that you can use to easily install and manage multiple node versions in your machine:

1. Install nvm https://github.com/creationix/nvm
2. nvm install (installs the node version specified in .nvmrc)
3. nvm use (use version from .nvmrc)

Install Yarn v1

In order to instal yarn just follow their official installation steps

Install dependencies

yarn install # or simply yarn

Development

Embark Server

You probably will not be doing changes on the Embark Server. In any case, you can run it locally by executing

yarn start

Observe tho that it doesn't count with live reload so you would need to restart it for it to pick up any changes added after having it started.

Embark Client Web

There are a couple of options to choose for the development of Embark Client Web. The most suitable will depend on the nature of the changes you intend to insert:

• If you want to add/update UI components used for displaying Embark flows in a isolated way, you probably want to use Storybook
• If you want to add/update code related with Embark flows processing and/or verify your changes in the context of the whole flow, the best option would be run your flow locally with Angel

Developing with Storybook

To start Storybook just run

yarn storybook

and then access http://localhost:6010/. If your components are not Storybooked yet make sure to first storybookify them.

Developing with Angel

Make sure you have the Angel project ready in your machine. Check Angel - Getting Started for more details.

1. Run Angel locally

cd <path-to-Angel-repo>
yarn watch

1. Run Embark locally

cd <path-to-embark-repo>
yarn watch

1. Access Angel locally by going into http://localhost:8080/ and load the desired flow in development mode.

With that done, any recent changes related with Embark Client Web code will be taken into account while previwing Embark flows in Angel.

Deploy

Embark Server

The Embark Server is dockerized and it is hosted on Hedvig's AWS plataform.

Staging

All you need to do to deploy Embark Server on staging is to merge your changes into master and wait for Codefresh to build the docker container. A message will be sent to #platform-deploy when the deployment process is finished.

Production

In order to deploy Embark Server on prod you'll need to use the prod-env/bin/help_me_deploy.py script; so make sure you:

1. Have cloned prod-env repository;
2. Have an AWS account configured by following this guide

Having met the prerequisites and after having deployed on staging and verfied your changes all you need to do is:

• cd to the prod-env repo
• Run help me to deploy script:

export AWS_PROFILE=dev
bin/help_me_deploy.py prod

• Choose embark as the service you want to deploy
• ...and follow the instructions. At some point you will be presented with a link to the diff between the commit you want to release vs. what's currently deployed in production. It's a good idea to look through all changes before proceeding with the deploy. You can follow the progress in the #platform-deploy Slack channel.

Embark Client Web

The Embark Client Web is distributed as a NPM package. It is published via a GitHub Action workflow to NPM.

Steps:

• Go to the Publish to NPM under the "Actions" tab.
• Trigger a new run with the version you want to publish, e.g. "4.2.1"
• A PR is created for you so that you can merge the new version to the master branch
  • Check out the PR branch and update CHANGELOG with your changes