Tech 101
This page is designed to provide information for this project accessible for folks besides our developers. It is heavily sourced from our existing documentation, but will focus on abstracting the concepts and answer questions about how we are using the technology within the application.
Placeholder for our selected AWS approach.
Placeholder for our Dev and Prod environments description.
What is Circle CI, and why are we using it? Basically, Continuous Integration means multiple developers pushing small, frequent changes to a shared repository or ‘master’. They are integrating changes continuously, rather than periodically, and thus–ta da!–Continuous Integration. If your tests pass, then you can deploy your code to development, staging, production, etc., automatically. (Sourced from CircleCi.com)
We are using CircleCI to automate our tests as well as our deployments. We have some more documentation that takes about our deployments in a little more detail.
What is React and why we are using it? React makes it painless to create interactive UIs. Design simple views for each state in your application, and React will efficiently update and render just the right components when your data changes. Declarative views make your code more predictable and easier to debug. (Sourced from reactjs.org/)
The front end is built in React, and uses the following libraries:
- react-router for page routing
- Redux for internal state management
- Webpack for bundling the app into a deliverable
- okta-auth-js for authenticating with Okta
(We have more detailed documentation about how our frontend build is configured, too).
We use the CMS Design System, as the foundation for styling, and add additional stylesheets where appropriate. We build our custom styles in Sass, a superset of the CSS standard that provides a lot of convenient and reusable patterns to cut down on new development time. Sass is converted into standard CSS as part of the build process.
For testing, we use Jest as the test runner and Enzyme and React-Testing-Library as React renderers.
The API is built on Express using a PostgreSQL database, and a handful of libraries:
- jwt-verifier for verifying the jwt authorization tokens received with the requests that were supplied by Okta
- okta-sdk-nodejs for interacting with Okta to retrieve user profiles
- Knex for interacting with the database
For testing, we use node-tap as the runner and assertions, and Sinon.JS for mocking.
If you want to get a little deeper into how the API works, we have documentation about:
- configuring the back end app (environment variables and stuff like that)
- our authorization model
- how we handle authentication
The API is also documented with OpenAPI. To see the
spec document, once the API is running, you can browse to its /open-api
endpoint. You can also use a hosted version of
Swagger UI to get a nicer visualization.
The current database model is presented here. The knex_* tables are used to manage migration versions by our database interaction library.
Placeholder for more information regarding testing
We also have documentation about how to run tests.
What is linting, and how do we use it? Code linting is a type of static analysis that is frequently used to find problematic patterns or code that doesn’t adhere to certain style guidelines. ESLint was created was to allow developers to create their own linting rules. ESLint is designed to have all rules completely pluggable. The default rules are written just like any plugin rules would be. They can all follow the same pattern, both for the rules themselves as well as tests. (sourced from eslint.org)
We use eslint to analyze our JavaScript files and find patterns / code that doesn't adhere to our style rules. Our rules are based on AirBnb's style guide and Prettier.
We use tota11y to manually test our pages during development for accessibility violations. Tota11y helps visualize how your site performs with assistive technologies. The process of testing for accessibility (a11y) is often tedious and confusing. In many cases, developers must have some prior accessibility knowledge in order to make sense of the results. Instead, tota11y aims to reduce this barrier of entry by helping visualize accessibility violations (and successes), while educating on best practices. Tota11y is a single JavaScript file that inserts a small button in the bottom corner of your document (sourced from http://engineering.khanacademy.org/posts/tota11y.htm).
We also utilize eslint-plugin-jsx-a11y for automated checks for a11y rules within React components.