OpenPRA MonoRepo

Welcome to the OpenPRA Monorepo, the unified codebase for the OpenPRA application suite. This repository uses the Nx build system, which encapsulates and manages a collection of packages. Together, these packages facilitate the maintenance of OpenPRA App, including the frontend, backend, wrappers for underlying C/C++ engines, shared TypeScript definitions, and utility packages for common functions.

For instance, the mef-schema package centralizes the OpenPRA-MEF (Model Exchange Format) definitions, while the shared-types package leverages these definitions to create TypeScript types and other shared data structures.

Additional Documentation

Additional documentation can be found in the Extended README section.

Table of Contents

• Packages
• Prerequisites
• Installation
  • nvm
  • node
  • pnpm
  • mongo
• Setup
• Development Steps
  • Command Line Usage
  • Installing Packages
• Troubleshooting
• License

Packages

Included within this monorepo are the following packages:

• engine-scram-node: Node.js wrappers for the SCRAM C/C++ engine.
• frontend-web-editor: A React v18 and TypeScript-based frontend UI.
• mef-schema: OpenPRA MEF JSON Schema definitions.
• model-generator: A tool for creating models from predefined schemas.
• shared-types: Shared TypeScript definitions for consistent data structuring.
• web-backend: A NestJS and TypeScript backend service.

Prerequisites

Before setting up the project, please ensure the following tools are installed on your system, instructions for which are provided in the following sections.

• pnpm (Package Manager)
• nvm (Node Version Manager)
• Node.js lts/iron
• MongoDB (for hosting a database)
  • [Optional] Native Mongo App
  • [Optional] Docker Desktop & Compose
• A Chromium-based web browser (for debugging in-browser Javascript with breakpoints)
• React Developer Tools

Installation

nvm

• Linux: Installation instructions can be found here.
• Windows: Download and install nvm-setup.exe.
• MacOS: Install Homebrew if not present with
  • /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
  • then brew install nvm

node

Once installed, nvm can be used to download and use the node version of choice. Install it using nvm with the following commands:

nvm install 20.9.0
nvm use 20.9.0

pnpm

• Windows: winget install pnpm.
• macOS: Install Homebrew if not present with
  • /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
  • then brew install pnpm
• Linux: Refer to the PNPM installation guide for your distribution.

mongo

Choose one of the two options below, not both!

• Docker Desktop

  • Install the Docker Desktop app for your OS.
  • Then, follow the instructions to install Docker Compose v2.
  • Be sure to skip the Native App step in this case.

• Native App

  • For ease of development on Linux/MacOS, we have typically been using Docker and docker compose to spin up MongoDB.
  • However, you can also just download MongoDB for your OS and run it directly. If you intend to do this, follow the official MongoDB installation guide for your OS.

React Developer Tools

• Install the React Developer Tools for your browser.
• Verify the installation by going to the React Website and opening Developer Tools on your Browser.
• You should have two additional tabs along with the already present ones - Profiler and Components.

Setup

Once prerequisites are installed, initialize the project with these commands:

pnpm setup
pnpm install
pnpm install --global [email protected]

Nx Migrations [Admin Only]

nx migrate 17.1.2
pnpm install --no-frozen-lockfile
## if migrations.json was created, run:
nx migrate --run-migrations

For Windows users experiencing issues with nx, adjust the PowerShell script execution policy:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

---

Development Steps

Review the WebStorm Config - Prettier & ESLint README.

1. Start the mongo database

Using one of the two options below, spin up an instance of the database

• Docker Compose

  • Set up a Docker-managed database environment with:

    docker compose -f docker/docker-compose.yml up -d

• Native App

  • You will need to figure out how to start the mongo server.

2. Start the web-backend debugger

To debug the frontend in JetBrains WebStorm using nx scripts:

1. Open the project in WebStorm.
2. Go to Run > Edit Configurations.
3. Add a new Nx configuration by choosing the web-backend.
4. Save the configuration.
5. Click the run icon to start the backend server. Once up, the debugger will attach to the running process.

3. Start the web-editor debuggers

To debug the backend in JetBrains WebStorm using nx scripts:

1. Open the project in WebStorm.
2. Navigate to Run > Edit Configurations.
3. Create a new Nx configuration for the web-editor.
4. Save and run the configuration.
5. Set up browser debugging following WebStorm's guide.

4. Other Targets

To debug any other build targets, or CommonJS, Typescript, or Node.js packages, follow these general steps:

1. Open the project in WebStorm.
2. Go to Run > Edit Configurations.
3. Click the + button to add a new configuration.
4. Choose Node.js for CommonJS or Node.js packages, or TypeScript for TypeScript packages.
5. In the JavaScript file field, specify the path to the file you want to run or debug.
6. For Node.js applications, you can also specify environment variables, node parameters, and the working directory if needed.
7. Save the configuration by clicking OK.
8. Click the run icon to start the application or the debug icon to start debugging.

---

Command Line Usage

You can always use the command line to serve or build any of the targets. nx supports a wide range of commands, so be sure to check out its documentation.

Some very basic examples include:

• Serve packages concurrently

nx run-many -t serve --all

• Serve packages individually:

nx serve web-editor

nx serve web-backend

nx serve shared-types

• Run Jest unit tests and linting across the project with:

nx run-many -t test

• Run ES linting across the project with:

nx run-many -t lint

Installing Packages

When working within the monorepo, it's important to understand the distinction between scoped packages and workspace-related packages. Scoped packages are those that are specific to a particular package within the monorepo, while the workspace package is the one defined by the package.json at the repo root.

To install a new package, use the following commands:

• For scoped packages (specific to a project):

  pnpm --filter=<project-name> install --save-exact <package-name>

• For workspace-related packages (global to the monorepo):

  pnpm -w install --save-exact <package-name>

The --save-exact flag is enforced to ensure that the exact version of a package is installed, which helps in maintaining consistency and avoiding issues with minor updates that may introduce breaking changes.

When installing packages, you also need to decide whether to use --save-dev or --save:

• Use --save-dev (or -D) for packages that are only needed during development or for building the project, such as linters, type definitions, or compilers.

  pnpm --filter=<project-name> install --save-dev --save-exact <package-name>

• Use --save (or no flag) for packages that are required at runtime by your package.

  pnpm --filter=<project-name> install --save --save-exact <package-name>

Testing

For package specific testing documentation, refer to the package's corresponding README.md file.

• frontend-web-editor

Troubleshooting

• If dependency issues arise, check for proper camel casing in frontend component filenames and adjust as necessary.
• If docker compose fails to work, you can confirm that your configuration is valid by running docker compose -f docker/docker-compose.yml config

License

This project is under the GNU AGPLv3 license, which requires that any networked use of a modified version of the software must make the source code available. For more information, visit AGPL-3.0 license details.