U.S. College Finder

Coforma's response to the HHS Swift

Table of Contents

• Overview
• Getting Started
• Testing
• Analytics
• Decision Documentation

Overview

User needs and business goals are the central focus of every solution Coforma builds. This tool will empower prospective students, assisting them in achieving their goal of going to college. You can check out the tool in two places.

• Test Environment link
• Production Environment link

If you'd like to work on this with us please check out our approach to contributing

Getting Started

Architecture

This prototype uses a serverless approach deploying on AWS. For more information on decisions made please see this folder. There are two main parts two the architecture.

1. A data ingestion piece that uses api access to large language models to complete the data set
2. An application set

Here is a link to the current architecture of the application

One time only

Before developing locally, you'll need to install some tools. You may have some of these already, or you may not.

• Install nvm:

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

• Use nvm to install specified version of node:

  cd <project-directory>
  nvm use # attempts to set local node version to repo-specified version
  nvm install # only needs to be run if nvm use cannot find correct version

• Install yarn:

  brew install yarn

• Install pre-commit:

  # only need to run one of the following
  brew install pre-commit
  pip install pre-commit

• Install pre-commit git hook scripts:

  cd <project-directory>
  pre-commit install # installs git hook scripts for repo

• Install adr-tools:

  brew install adr-tools

Before making commits

This repository requires signed commits, so you will need to configure them. See instructions on GitHub.

Running the local development server

To run the local development server:

yarn install # checks dependencies and installs as needed
yarn dev # runs the development server

Open http://localhost:3000 with your browser to see the locally running application.

Connecting to DynamoDB locally

Export AWS Credentials for a user with access to the AWS DynamoDB in your terminal before running the application

Testing

Unit Testing

We use Jest and React Testing Library to facilitate unit testing. Unit tests can be run manually via the CLI, but will also run on every commit for each branch in the CI pipeline.

To run manually, do one of the following:

yarn test # runs all unit tests
yarn test:cov # runs all unit tests and reports coverage

Code Quality and Test Coverage

We use Code Climate for automated code review. You can track test coverage and maintainability by clicking the links at the top of this document.

Integration Testing

We use Cypress to facilitate integration and end-to-end (e2e) testing. Integration tests can be run manually via the CLI, but will also run on every commit for each branch in the CI pipeline.

To run manually, do one of the following:

yarn test:cy:run # runs all cypress tests
yarn test:cy:open # opens the browser-based cypress ui so tests can be individually selected and run

Accessibility Testing

We use axe for automated accessibility testing. Additionally, unit tests make use of the jest-axe library, and integration tests make use of the cypress-axe library.

These tests can be run manually via the CLI by running unit tests and integration tests, but will also run on every commit for each branch in the CI pipeline.

Analytics

Mixpanel is a customer and product analytics platform that we use to track analytics related to traffic and user behavior. This helps us better meet user needs by monitoring application usage so we can improve product performance and behavior.

It's best practice to separate your tracked data by environment. We have two separate Mixpanel projects set up: Test (used for testing conducted in lower environments) and Prod (used for tracking production data). This data can be seen after invitation and authentication.

Using Mixpanel

Mixpanel has excellent documentation for JavaScript, which can be found in the JavaScript documentation here. This includes information on user and event tracking. While client-side tracking is necessary to an extent, server-side tracking is more reliable. Documentation for server-side tracking can be found in the Node.js documentation here.

Decision Documentation

Using adr-tools

This repository makes use of adr-tools to record architectural decisions as part of the code base.

There are two uses for this, recording a new decision and superseding an existing decision.

Recording a new decision

To create a new decision use the adr new command:

 adr new <decision-title>

Superseding an existing decision

To overwrite an existing decision you can add the -s flag followed by which is getting overwritten. In this example we are overwriting decision 9 with an updated decision:

adr new -s 9 <decision-title>