ISO15926vis

Web interface to visualise the ISO 15926 Reference Data Library.

Introduction • Getting started • Development • Deployment • Credits

Introduction

ISO15926vis is an interactive graph visualisation for the equipment Reference Data Library (RDL) described in the ISO 15926-4 Standard.

This project assists in navigating the hierarchical relationships of classes defined by the RDL, accessible through the current RDL browser on which the hierarchy can be difficult to interpret.

The project is currently deployed at https://iso15926vis.org/.

Getting started

These instructions will install dependencies get a copy of the project up and running on your local machine.

Installing dependencies

This project consists of a Vue client, Flask server, and command-line interface. Dependencies must first be installed before running any of these.

Git clone

Git clone the repository:

git clone https://github.com/nlp-tlp/15926-4-RDL-CITS3200.git

Client dependency installation

If you intend to run the client, download NVM from the official source or using a package manager for your OS. Then, use NVM to install NPM.

Install NPM dependencies in the root directory for Husky Git hooks and initialise Husky:

npm i

# If developing:
npx husky-init
cp .husky/pre-commit.example .husky/pre-commit

Install NPM dependencies for the client from the root directory with:

npm i --prefix src/client

Server / CLI dependency installation

It is recommended that you install the server / CLI Python packages in a virtual environment. Install the dependencies from requirements.txt:

pip install -r src/server/requirements.txt

Running the project

The following instructions can be used to run the Vue client, Flask server, and command-line interface locally for development.

Client

To access the Vue web interface, run from the root directory:

cd src/client
npm run dev

Server

To run the Flask server, activate your virtual environment and run from the root directory:

cd src/server
flask --app "server.py" run

NOTE: A database must exist before adequate usage. Please consult the CLI section to update the database.

CLI

To run the CLI for the Flask server:

cd src/server
./cli.py

Follow the directions given in the CLI menu to modify the database and view other parameters. The database should first be updated on initial clone. This is done by selecting option U on the main menu. This method should not be used for docker deployments. Please consult the later section for that.

Development

The following sections include instructions for testing and adding dependencies, for use by developers.

Testing

Testing frameworks have been set up for project functionality.

Server tests

Tests for the Flask server and CLI are written with Pytest. It is recommended that you activate your virtual environment first (e.g. venv), then run in the root directory:

cd src/server
pytest

Client tests

Tests for the Vue client are written with Vitest for unit tests, and Playwright for end-to-end tests, the commands for which have been added as npm scripts.

Run in the root directory (unit / e2e depending on what is wanted):

cd src/client
npm run test:unit
npx playwright install
npm run test:e2e

Vitest also offers the capability to continuously test and provide immediate feedback as changes are polled through Vite. If you would like this behaviour, change the script in src/client/package.json from "test": "vitest run" to "test": "vitest". Note that these commands cannot be run as terminal commands.

Adding dependencies

Follow these steps if you need to add a package during development

Adding to client

Packages are added through NPM in the client directory.

For any dependencies that should be there in the production environment, run:

npm i <package_name> --save

For any dependencies needed for development but not the production environment (e.g. type checking with ESLint), run:

npm i <package_name> --save-dev

Adding to server / CLI

Packages should be added through pip in your virtual environment:

pip install <package_name>
pip freeze > requirements.txt

Deployment

Docker

You can host the client and server locally with Docker. This requires the Docker CLI to be installed with docker compose.

Note that changes to main files (dependencies, settings, etc.) require the containers to be rebuilt.

From the root directory, run:

cd src
cp .env.example .env
docker compose up --build

⚠️ If using WSL, the docker desktop app must be installed and configured for WSL. ⚠️

Running the CLI

To access the CLI inside of the docker container, run :

docker exec -it Server /app/cli.py

Credits

This project was developed by students of the University of Western Australia (UWA) as part of the unit CITS3200 (Professional Computing), as Team 14 of the 2024 Semester 2 cohort.

Our team members include: Cameron O’Neill, Heidi Leow, Paul Maingi, Ryan Dorman, Shuai Shao, and Vinita Rathore.