Skip to content

cfpb/hmda-frontend

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

HMDA Frontend Projects

Static Badge

The HMDA Frontend monorepo hosts the public facing applications for the collection, publication, and navigation of millions of HMDA records per year. This repository combines six, previously separate, React application repos in order to simplify component sharing, synchronize versioning of common dependencies, and improve rendering efficiency when navigating between apps.

Contents

Technical Overview

Each React application lives in it's own sub-directory of the /src folder, with shared assets and components housed in /common. All sub-applications are rendered as asynchronous components within an application shell /App.jsx that provides a common header. This approach eliminates unneccesary reloading of the site-wide navigation, giving the separate apps a more connected feel. React Router is used for client side routing with React Redux integrated for state management of the more complex apps, such as Filing. Unit tests are developed using Enzyme and end-to-end testing performed with Cypress. Dependencies are managed with yarn.

Applications

HMDA Homepage

HMDA Homepage is a single-page app providing easy access to the HMDA applications, tools, data products, and documentation.

HMDA Filing

The HMDA Filing Platform UI allows lending institutions to submit HMDA records, resolve errors, verify edits, review submission status and history, and sign submissions.

HMDA User Profile

The HMDA Profile page is designed to update associated institutions with the logged in account. Once the associated institutions have been added to your account, you can now file for those institutions.

HMDA Data Browser

The HMDA Data Browser enables users to easily filter and download aggregated HMDA datasets.

HMDA Platform Tools

The HMDA Platform Tools assist filers in the preparation of submission data, including calculation of Rate Spread, generation and validation of Check Digits, as well as submission file generation and format verification.

HMDA Documentation

The HMDA Documentation site provides product FAQs, detailed Filing instructions, data publication schema and usage guides, as well as direction for using the HMDA Tools. Documentation content is hosted as easily editable Markdown files, loaded using Docusaurus. This allows updates to be pushed to Production without a project redeployment. Docusarus search is powered by Algolia through the DocSearch program.

HMDA Data Publication

HMDA Data Publication provides datasets and reports of HMDA data collected in or after 2017 which, combined with Census demographic data, can be used for data analysis purposes.

HMDA Data Publication - Updates and Notes

Publication Updates and Notes provides a searchable change log of updates, releases, and corrections to published HMDA Data. Visit the Updates and Notes FAQ for details.

Development

Requirements

  • Node >= v20.8.0
  • Yarn berry >= v4.0.2

Installation

  • Clone repo
  • Run yarn from repo root to install depencencies

Running Locally

Several components of the Frontend (ex. Filing, Data Browser) require a connection to the HMDA Platform in order to operate. You can find instructions for the running the HMDA Platform locally here.

HMDA Help requires a connection to the HMDA Institutions API in order to operate. You can find instructions for the running the HMDA Institutions API locally in the README. Note that having the HMDA Platform running is a pre-requisite to starting the HDMA Institutions API.

If your development does not require this integration, yarn start will run the development server, opening a browser window to http://localhost:3000.

Integrating with the Filing application

By default, the locally running Frontend is configured to use the Filing API from the locally running Platform. In order to go through the Filing process, there are a few elements that need to be completed first:

  • Create Institutions (Platform)
  • Bypass API authentication (Platform)
  • Configure the UI (Frontend)
Create Institutions

Before you can submit a Filing you need to have an Institution created on the Platform for each year you want to test. The following command will generate the required data for the default test Institution, for all currently available filing periods. You need to have the HMDA Platform started before running this command:

yarn ci-data

To create data for an Institution other than the default FRONTENDTESTBANK9999, you can modify cypress/ci/config/institutions.json and rerun the above command.

This Institution loading needs to be done each time the HMDA Platform is restarted.

Bypass API Authentication

On the Platform, you will need to set an environment variable to prevent the API from requiring an authentication token for incoming requests. If already running, you will need to restart the Platform.

export HMDA_RUNTIME_MODE=dev
Configure the UI

If you will be testing against an Institution that is not the default, you can configure this via a VITE_* variable:

VITE_LEIS=INSTITUTION1,INSTITUTION2

Second, you will need to bypass Frontend authentication. This is most easily done by running the Frontend the way we do in a Continuous Integration environment:

yarn ci

To combine these configuration options

VITE_LEIS=INSTITUTION1,INSTITUTION2 yarn ci

You can now visit the filing application at http://localhost:3000/filing.

Running via Docker

To see the application running in a container you can run:

docker build -t hmda/hmda-frontend .
docker run -p 8080:8080 hmda/hmda-frontend

To build using docker-compose:

docker-compose build

Code Formatting

The prettier formatting tool the formatter of choice for this repo.

Prettier Format API: https://prettier.io/docs/en/options.html

The .prettierrc.json file contains the specific formatting for each file.
The .prettierignore file will ignore formatting any directories or files listed.

In order to have Prettier properly format the developers code there are a few steps that developer needs to take.

  1. Install the Prettier code extension

  1. Update the developers Visual Studio Code user settings to use the Prettier formatter as the default formatter

First open your settings.json file by clicking View at the top of VS Code then click Command Palette and then type what is in the screenshot below.

Now we need to add 2 lines of code to our JSON file.

"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,

The newly added lines tell VS Code to use Prettier as the default formatter and will format the code when the file is saved.

Helpful Prettier formatting scripts

Running all files:

npx prettier --write

Directory Specific:

npx prettier --write {enter-directory}

Check files formatting:

npx prettier --check

The above command will return in the terminal what files have not been formatted by prettier.

NOTE: formatting settings that prettier cannot do:

  • Format on Paste
    • "editor.formatOnPaste": true,
  • Themes
  • Icon Themes

Adding GIFs

Why GIFs? GIFs provide a better visual repesentation of how a parituclar part of the UI functions.

Examples that are already in our README

Record video to turn into GIF

Navigate to Apple support native screenshot & recording controls to learn how to use MacOS controls.

Create recording bounds
On your Mac, press Shift-Command-5 (or use Launchpad) to open Screenshot and display the tools. Drag the bounds to be where it needs to be for recording the video.

Navigate to Apple support how to record with QuickTime Player.

Convert video file to .gif

Small file size + lower quality video to gif converter.
Large file size + higher quality video to gif converter.

Store the GIF in the Frontend

Navigate to the readme-files directory and upload the .gif extension this directory.

How to use GIF in README

Paste the below code to the section you want to import your GIF and update the name-of-gif pieces.

<a href='./readme-files/name-of-gif.gif' alt='name-of-alt'>
  <p align='center'>
    <img src='./readme-files/name-of-gif.gif' width='80%'  overflow='scroll'/>
  </p>
</a>

Testing

Unit Tests

yarn test

Enzyme enables isolated testing of React components. Unit tests providing verification of feature implementation while also serving as suite of regression tests.

End-to-End Testing

yarn run cypress run

Cypress is used to perform end-to-end testing of the filing application, tools, data publication products, and data browser. It mimicks a user's interaction with the site and allows for rapid, automated system validation of project deployments.

Cypress automated filing test