Skip to content
This repository has been archived by the owner. It is now read-only.

cds-snc/cra-claim-tax-benefits

main
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
api
 
 
bin
 
 
 
 
 
 
db
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

La version française suit.

Claim tax benefits / Déclaration de revenus pour un accès aux prestations

This is a demo of a service to make tax filing faster and easier for a preselected group of eligible low-income Canadians. This service was designed and developed by the Canadian Digital Service (CDS) in partnership with the Canada Revenue Agency (CRA).

CRA already has most of the information that tax-filers include in their returns. At the same time, low-confidence tax filers are very worried about making mistakes when submitting a tax return. Using this information, we aimed to design a service that provides a wizard-like tax filing experience: rather than requiring tax-filers to enter their information, the service presents information that the CRA already has, then asks tax-filers to confirm the information is correct.

Demo user 1 Demo user 2
Gabrielle Roy Monique Corriveau
A5G98S4K1 A5G98S4K3
540 739 869 435 073 143
09 09 1977 03 03 1947

While this repository is no longer actively maintained, the code is open and available for demonstration purposes or reuse. In addition to an end-to-end flow, it is an example of best-practice development for an API-driven, cloud-native frontend application.

Table of contents

Technical overview

The Claim Tax Benefits (CTB) application is a server-side express application using Pug templating on the server and schnazzy SCSS stylesheets. The application scaffolding comes from the express generator. It assumes the existence of a backend API (to receive user data) and a cloud database (for storing access codes), although both are stubbed out so the application can run in isolation for development purposes.

There is a record of the decision to go for Express, for posterity.

As mentioned in the introduction, the CTB application implements many recommended practices for a modern web service.

Use of third-party services

We use several third-party services for an improved development workflow and continuous security.

  • GitHub is a cloud-based service that stores our source code, tracks code changes and facilitates code reviews
  • GitHub Actions is a Continuous Integration and Deployment (CI/CD) service that allows us to test and deploy our code right from GitHub
    • CI/CD services abound, but we used GitHub Actions because it was easy to set up, and with its yml-based configuration it would be easy to move away from
  • Heroku is a fully-managed platform as a service. We use Heroku Review Apps to build disposable applications per pull request, facilitating code reviews.
  • Snyk is a software as a service product that scans through our dependencies for packages with known issues. It alerts us when a version of a package we’re using has a known exploit.
  • LGTM is a software as a service product for continuous security analysis. It analyzes each pull request for potential security vulnerabilities.

Automated tests

All new pull requests have a suite of automated tests run against them.

  • Jest: Unit tests to verify correct internal logic for components
  • ESLint: JavaScript linter that ensures uniform JS throughout the app
  • Cypress: End-to-end behaviour-driven tests that run through desired user flows
    • cypress-axe: We run an accessibility scan per page (using axe) to check for violations in the markup

Development workflow

Continuing development

A walkthrough on how to continue development on this project: whether your aim is to rebuild the service in a new technology or to develop and release this codebase specifically.

Getting started (npm)

Install npm

npm is a javascript package manager. It downloads project dependencies and runs node applications.

npm will complain if you’re not on node version v10.15.0 or higher when you boot up the app.

.env file (optional)

It’s possible to bootstrap this application with no /.env file — but if you want one, go nuts.

Example `.env` file
# environment
NODE_ENV=development
PORT=4300

Build and run

Guess what? There is no build step. Just install the dependencies and run it.

Pretty slick. 😎

# install dependencies
npm install

# run application in 'dev' mode
npm run dev

# run application in 'prod' mode
npm start

The app should be running at http://localhost:3005/. With npm run dev, saving a file will restart the server automatically.

On a Mac, press Control + C to quit the running application.

Run with local postgres DB

The application can be run with a local postgres database (otherwise, it falls back on a JSON file).

To start the app in development mode, alongside the postgres db type docker-compose up

Docker Desktop already has compose included, but just in case, installation instructions for docker-compose can be found here

Run tests

# run unit tests
npm test

# run linting
npm run lint

# run end-to-end tests
npm run cypress
npm run cypress:cli # these don't open a browser

Using Cypress

Cypress is what we use to write our end-to-end tests. It can run in a browser or in headless mode (ie, on the command line) to step through one or more flows. By running our end-to-end tests frequently, we are making sure that new changes to the code don't break existing user journeys.

Using Docker

Install docker

A docker container allows a developer to package up an application and all of its parts. This means we can build an app in any language, in any stack, and then run it anywhere — whether locally or on a server.

Build and run as a Docker container

# build an image locally
docker build -t claimtaxbenefits.azurecr.io/cra-claim-tax-benefits .

# run the container
docker run -it -p 3005:3005 claimtaxbenefits.azurecr.io/cra-claim-tax-benefits

The container should be running at http://localhost:3005/.

On a Mac, press Control + C to quit the running docker container.

Deploying the app

This application is deployed continuously using Github Actions.

However, it’s still a beta service so it might not be 100% reliable. If anything goes wrong, follow the manual deployment instructions.

---------------------------------------------------------------------

Réclamation d’avantages fiscaux

L’application Réclamation d’avantages fiscaux n’est pas autonome et nécessite un niveau élevé d’intégration de la part de l’ARC. Ce produit extrait les données sur l’individu à partir de la base de données de l’ARC, puis les affiche au déclarant. La communication entre le produit et la base de données de l’ARC se fait par l’intermédiaire d’une interface de programmation d’application (API). Cette technologie permet à un système de communiquer avec un autre système.

Une fois que le déclarant s’est authentifié, l’API envoie les données à l’application. Celle-ci demande ensuite au déclarant de confirmer que l’information affichée est exacte. La déclaration de revenus est ensuite produite au moyen de l’API IMPÔTNET, c’est-à-dire la même que celle utilisée par les logiciels payants.

Étant donné que l’ARC utilise des technologies héritées, il existe un degré de risque. Ce risque est atténué par le fait que le produit en ligne est hébergé sur une technologie en nuage, de sorte qu’il est séparé de la base de données. Cette séparation nous a permis de réaliser plusieurs prototypes pour différentes versions, sans mettre en péril les données de l’ARC. Si le produit était devenu un service fonctionnel, nous aurions pu continuer à modifier le service en fonction des commentaires des utilisateurs.

Table des matières

Aperçu technique

L’application Réclamation d’avantages fiscaux (RAF) est une application express côté serveur qui utilise les langages Pug pour les gabarits et SCSS pour les feuilles de styles. L’échafaudage de l’application vient du générateur d’applications Express. Il suppose l’existence d’une API backend (qui reçoit les données de l’utilisateur) et d’une base de données infonuagique (qui stocke les codes d’accès), bien que tous deux soient simulés afin que l’application puisse fonctionner de façon isolée pour le développement.

Le compte-rendu de la décision d’opter pour Express (anglais seulement) est conservé pour la postérité.

Comme il est mentionné dans l’introduction, l’application RAF met en œuvre plusieurs pratiques recommandées pour le développement de services Web modernes.

Utilisation de services tiers

Nous utilisons plusieurs services tiers pour améliorer le déroulement du développement et de la sécurité continue.

  • GitHub est un service infonuagique qui stocke notre code source, suit les changements au code et facilite les revues de code.
  • Actions GitHub est un service d’intégration et de déploiement continus (CI/CD) qui nous permet de tester et déployer notre code directement à partir de GitHub
    • Il y a beaucoup de services CI/CD, mais nous avons choisi Actions GitHub car il est très facile à installer, et il serait facile de s’en départir en raison de sa configuration de base yml
  • Heroku est une plateforme comme service (PaaS) complètement gérée. Nous utilisons Review Apps de Heroku pour construire des applications jetables à chaque demande de tirage, ce qui facilite la revue de code.
  • Snyk est un logiciel comme service qui passe à travers nos dépendances pour voir s’il y a des problèmes. Nous recevons des alertes lorsque la version d’un progiciel a des vulnérabilités connues.
  • LGTM est un logiciel comme service qui effectue l’analyse continue de la sécurité. Il fait une analyse à chaque demande de tirage pour trouver les vulnérabilités de sécurité potentielles.

Tests automatisés

Chaque demande de tirage subit une suite de tests automatisés.

  • Jest : Tests unitaires servant à vérifier la logique interne des composants
  • ESLint : Linter JavaScript qui assure une uniformité du code JavaScript dans toute l’application
  • Cypress : Tests basés sur le comportement qui s’exécutent pour vérifier les étapes des parcours utilisateur
    • cypress-axe : Nous effectuons un balayage de chaque page afin de vérifier les violations d’accessibilité dans le code

Continuer le développement

Guide pour continuer le développement du produit : Ce guide est là pour vous aider si vous voulez reconstruire le service avec une nouvelle technologie ou si vous voulez développer et déployer le code.

Construire et exécuter l’application

Veuillez vous référer à la page README afin d’obtenir les instructions détaillées pour construire et exécuter l’application.

About

A benefit signup prototype by the Canadian Digital Service

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published