# frontend-royalties

This is the repo for the ABACUS frontend react application. It is an internal tool part of the [Orchard Suite](https://github.com/theorchard/orchard-suite/tree/master/packages).

## Requirements

- Node >= 24
- Yarn
- An AbacusProfile

```bash
brew upgrade node
brew upgrade yarn
```

## Setup

Follow the [Javascript Package Management Setup](https://github.com/theorchard/docs/blob/master/javascript/packages.md) guide to setup access to our private NPM repository.

```bash
# install dependencies
yarn

# create environment configuration
cp .env.shadow .env

# create local feature flags
cp setup/frontend.local.json.shadow frontend.local.json
```

## Available Scripts

In the project directory, you can run:

### `yarn start`

Runs the app in the development mode.<br />
Open [http://localhost:8080](http://localhost:8080) to view it in the browser.

The page will reload if you make edits.<br />

**NOTE:**
**Running the project locally requires an active VPN connection.**

### `yarn test`

Runs all unit and linting tests. Run this before creating a PR.

### `yarn test:unit --watch`

Runs the jest unit tests in watch mode. In watch mode type `p` to enter a filter.

### `yarn build`

Builds the app for production to the `build` folder.<br />
It bundles React in production mode and optimizes the build for the best performance.

Note that this command is not required to run locally, it is run during the build steps in jenkins.

### `yarn run`

Shows all available tasks.

### `yarn install`

Upgrade all local libraries

## Building a Docker Image

```sh
docker build -t royalties/frontend .
```

## Setting Up A Full-Stack Development Environment

The instructions below are _optional_. Running `yarn start` should be enough to bring up a frontend locally. But it will be running against a **QA** backend and database.

That being said, docker can be used to develop locally. There are a variety of reasons to do this, notably:

- When running the app with the default `.env` settings, the local dev environment will actually be pointing to the **QA** `royalty_accounting` database
    - Use docker to spin up a local database to have more control over the data used to test local changes
    - Use a dockerized DB to avoid polluting the QA database with test data
- Maybe some changes were made locally to the database or to an underlying microservice and they have not yet been merged/deployed to QA
    - Use docker to spin up the microservice locally to develop against these backend changes

In order to perform full-stack development the following will need to be up and running:

1. Local database instance
2. A local OWS service with API endpoints (connected to the local DB)
3. A local GraphQL instance (connects and combines application APIs)
4. This app, frontend-royalties (connected to GraphQL)

The instructions below explain how to do this. They use `ows-abacus-contract`, but can be applied to any ABACUS microservice.

### Run a Local OWS Service

In a local fork of the ows service:

1. Copy the `.env.shadow` to a `.env` file.
2. Make sure the the `.env` file is using the MySQL docker container's DB credentials (found in [docker-compose.yml](https://github.com/theorchard/ows-abacus-contract/blob/master/docker-compose.yml#L8)):

```
MYSQL_DB_HOST=127.0.0.1
MYSQL_DB_USER=royalties
MYSQL_DB_PASS=1234
MYSQL_DB_NAME=royalty_accounting
MYSQL_DB_PORT=6350
MYSQL_TEST_DB_NAME=royalty_accounting_test
```

3. Bring up an empty database in the OWS service using `make start_db`.
4. Start the ows service to make API endpoints available locally using `make dev`.
5. The OWS service will start on `127.0.0.1:5000`.

### Run A Local GraphQL Layer

This frontend app uses GraphQL to interact with the OWS APIs. The default `GRAPHQL_URL` in frontend-royalties `.env` points to the **QA** GraphQL instance.

To have frontend-royalties use a local database and/or local OWS service, the `GRAPHQL_URL` env var should instead point to a locally running GraphQL Server.

But first, that GraphQL Server needs to be running.

In a local fork of [graphql-abacus](https://github.com/theorchard/graphql-abacus):

1. Copy the `.env.shadow` to a `.env` file.
2. Edit the service URL in the `.env` file to point to the OWS service running locally (done in the previous section).

- For example, change `OWS_ABACUS_CONTRACT_URL=https://qa-ows-abacus-contract.theorchard.io/` to `OWS_ABACUS_CONTRACT_URL=http://127.0.0.1:5000/`

3. Run the GraphQL server with command `yarn start`
4. GraphQL will be running at `localhost:8080/graphql`

### Use the Local GraphQL Server

As mentioned in the previous section, now that a local GraphQL Server is running, `frontend-royalties` can run against it. Update the `GRAPHQL_URL` env var in the `.env` file to `GRAPHQL_URL=http://localhost:8080/graphql`.

To avoid port collision with GraphQL, update the `CLI_SERVER_PORT` env var from `8080` to something else, like `6005`.

### Run Local ABACUS

Now start the frontend application as usual using `yarn start` and visit `localhost:8080` (or `localhost:6005` if the `CLI_SERVER_PORT` was changed).