openfisca / legislation-explorer

Explore legislation formulas and parameters.
https://legislation.demo.openfisca.org
GNU Affero General Public License v3.0
26 stars 12 forks source link
better-rules legislation-as-code microsimulation rules-as-code

OpenFisca Legislation explorer

A web user interface to explore an OpenFisca tax and benefit system.

This application consumes a legislation description made available by the OpenFisca web API and makes its parameters and formulas searchable and interlinked. Example.

Development stack

This application is based on Node on the backend and React on the frontend.

In order to run the server or to improve the app, first install Node and NPM and Git. Then, run the following commands:

git clone https://github.com/openfisca/legislation-explorer.git
cd legislation-explorer
npm install --production

Configure your instance

You will need to tell the Legislation Explorer server where your OpenFisca API instance can be reached, as well as where your repository resides for contributors to be directed to. This is all done through environment variables, allowing you to use the same code for any instance by injecting these elements at runtime.

To set these options, you need to define them by prefixing the npm start or npm run dev commands with their definitions, in the $NAME=$VALUE syntax.

If it gets lengthy or you want to persist these values, you can also use a .env file. Such a file is a plaintext file with name .env stored in the root directory of your legislation explorer instance (i.e. next to the package.json file). List all of your environment variables in the $NAME=$VALUE syntax, one per line. If you have trouble writing this file, read the parsing rules. An example file is provided as .env.example, setting default values. You can copy it, but changing it won't have any impact: only a file named .env will be taken into account. You should not commit this file: it depends on each instance.

Localisation (l12n / i18n)

The user interface of the legislation explorer has full support for internationalisation. Supported languages can be found in the src/assets/lang directory, and can be added by simply creating a new file with the two-letter language code to add support for.

For localisation, you can override any of the strings defined in these files through the UI_STRINGS environment variable.

The value is a JSON-encoded object whose keys are ISO two-letters language codes and values are strings, these values will take precedence over any strings defined in the lang folder.

The following strings are strongly recommended to be overridden:

Analytics

This web app supports Matomo (ex-Piwik) analytics out of the box. To set it up, use the following environment variables:

Server and public URL

Development-specific options

Run the server

cd to the cloned legislation-explorer directory, and run the following commands:

npm run build  # compile the frontend code
npm start  # start the server

Improve the app

You can edit all files in the source folder you cloned. In order to ease development, a different set of commands will allow you to run the app with hot module replacement, which will reflect your changes almost instantly rather than rebuilding the whole package.

cd to the cloned legislation-explorer directory, and run the following commands:

npm install  # install development dependencies
npm run dev

Some additional commands can be useful for development. You can discover all of them by running npm run.

Tests

This app has both unit and integration tests. Its integration tests are implemented with Watai. You will first need to install its Selenium WebDriver dependencies to run these tests.

Then, build the app, run the server, run a Selenium instance and, in another Terminal, run:

npm run test

Deploy to production

See the dedicated guide.