Recipe.Report

This is the monorepo for all recipe.report packages.

Backend

Written using Node.js/Express.js/Inversify.js/TypeScript, following the Domain-Driven Design approach.

The API server is broken up into a multilayered architechture that implements a service/repository pattern. The API layer, the service layer, the business/domain layer, and the data access layer (repositories implemented through the unit-of-work pattern).

Data is persisted using PostgreSQL, without an ORM. Connection to the database is made through the pg library, and all access to data happens via parameterized stored functions. The database owner and the database app user are separate, with proper access levels.

Env vars

The following environment variables (showing development values here) provide an example of the environment variables required in production. Environment variables may be set in the /etc/environment file on a Linux host system:

export NODE_ENV="development"
export RR_PORT="1138"
export RR_CRYPTO_KEY="MqSm0P5dMgFSZhEBKpCv4dVKgDrsgrmT"
export RR_CRYPTO_ALGO="aes-256-cbc"
export RR_CRYPTO_IV_LENGTH="16"
export RR_JWT_SECRET="devTestEnvironment"
export RRDB_USER="dbuser"
export RRDB_OWNER="dbowner"
export RRDB_HOST="localhost"
export RRDB_DATABASE="recipedb"
export RRDB_PASSWORD="dbpass"
export RRDB_PORT="15432"
export RRDB_URL="jdbc:postgresql://localhost:15432/recipedb"
export RRDB_MIGRATIONS="filesystem:./migrations"
export RR_LOG_TARGETS="trace.log+%json,stdout:warn%simple"

Development

Prepare the development database, install dependencies, and then start the API server.

Database

Prepare a development copy of the Recipe.Report database.

HashiCorp Vagrant is used to make setting up a development database quick and easy. Download and install Vagrant. Vagrant relies on "providers" such as VirtualBox, VMware, or HyperV, so install one of those.

From the data package directory (recipe-report/packages/data/), run the vagrant up command to create and configure a Vagrant VM running PostgreSQL. Once the development database is running, run the npm run flyway command to download Flyway. Next, run the npm run migrate command to apply database migrations.

cd ~/recipe-report/packages/data
vagrant up
npm run flyway
npm run migrate

Install

The Recipe.Report packages are organized into a monorepo. Install dependencies from the root directory (~/recipe-report/). Node.js and npm must be installed installed before running this command.

cd ~/recipe-report
npm install

Style, linting, updates

Run these commands from the api package directory (~/recipe-report/packages/api/).

Run the npm run prettier command to format the source code using the Prettier opinionated styling. Run the npm run linter command to identify and report ESLint code pattern findings. These can also be run automatically as IDE extensions.

Run the npm run updates command to check for dependency updates.

cd ~/recipe-report/packages/api
npm run prettier
npm run linter
npm run updates

Start the API server

Run these commands from the api package directory (~/recipe-report/packages/api/).

When you're ready to see it in action, run the npm run develop command to start the Recipe.Report API Server in development mode. This will run both the npm run build command to compile the TypeScript into plain JavaScript, and the npm run start command to run that compiled JavaScript.

npm run develop

API Endpoints

User

Users can register, activate, and then access the application. Users are linked to accounts with roles.

In the rr.users_to_roles table, a record links a user, a role, and an account.

User passwords must pass minimum complexity according to zxcvbn.

Account

Accounts have a primary user contact, in addition to users who are linked to accounts with roles.

Most data, such as Recipes, belong to accounts.

Role

Roles establish a level of access to an account.

Example roles:

Feature

Features are accessible to users based on account roles. For example, all users with any role/level for an account can access the recipe list feature for that account. Other features might only be accessible by users with a role/level 3 and above for an account, or only by level 6, etc.

Production

Instructions for setting up a production environment for the Recipe.Report API are outside of the scope of this readme document. Currently the production API instance runs Debian Linux, uses Uncomplicated Firewall, uses Nginx as a reverse proxy, and manages the Node.js process for the API using the PM2 process manager. Domain DNS is pointed to Cloudflare and Nginx is configured to require authenticated origin pulls. Deployments happen through GitHub Actions.

Frontend (React App)

Written using Node.js/React/Redux/Thunk/TypeScript, using React Hooks.

You can find information on how to use TypeScript with Redux Toolkit.

Development

Install dependencies, and then start the React development server.

Install

The Recipe.Report packages are organized into a monorepo. Install dependencies from the root directory (~/recipe-report/).

cd ~/recipe-report
npm install

Style, linting, updates

Run these commands from the react-app package directory (~/recipe-report/packages/react-app/).

Run the npm run prettier command to format the source code using the Prettier opinionated styling. Run the npm run linter command to identify and report ESLint code pattern findings. These can also be run automatically as IDE extensions.

Run the npm run updates command to check for dependency updates.

cd ~/recipe-report/packages/react-app
npm run prettier
npm run linter
npm run updates

Start the React app

Run these commands from the react-app package directory (~/recipe-report/packages/react-app/).

When you're ready to see it in action, run the npm run develop command to start the Recipe.Report React app in development mode. This will run the npm run build command which runs both the less-watch-compiler command and the react-scripts start command,

cd ~/recipe-report/packages/react-app
npm run develop

Tips

React developer tools

In the browser, install the React Developer Tools extension. Firefox. Chrome. Edge.

Once that is installed, you can view the Redux store while debugging in the browser inspector.

First, select a component in the React developer tools Components tab, and then go to the browser console and type $r to access the instance of that React component. To see that component's Redux store try $r.props.store.getState().

There is also Profiler tab to assist with optimizing performance.

Production

Instructions for setting up a production environment for the Recipe.Report React app are outside of the scope of this readme document. Currently the production React app instance runs Debian Linux, uses Uncomplicated Firewall, and uses Nginx as a web server. DNS is pointed to Cloudflare and Nginx is configured to require authenticated origin pulls. Deployments happen through GitHub Actions.

Testing

Run the npm t command to run Jest unit tests and create test coverage reports.