add readme

Author: assynour

README.md

@@ -0,0 +1,61 @@
+# Integration between `bpmn-visualization` and `pm4py`
+This is an example integration between [bpmn-visualization](https://github.com/process-analytics/bpmn-visualization-js/) and [PM4PY](https://github.com/pm4py).
+
+## Architecture
+The application consists of two main components: the frontend written in JavaScript and the backend written in Python. 
+* The frontend uses **bpmn-visualization** to visualize the BPMN process model and the statistics data over it. 
+* The backend is built using **pm4py** which processes data to perform process discovery and conformance checking. The results are then communicated to the frontend through [Flask](https://flask.palletsprojects.com/) and [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+
+In addition to bpmn-visualization and pm4py, the application also leverages two other libraries, [d3](https://d3js.org/) and [BPMN layout generators](https://github.com/process-analytics/bpmn-layout-generators). 
+* **d3** is used to manipulate colors and add a legend to the visualized BPMN diagrams.
+* **BPMN layout generators** is used to generate the layout of the discovered BPMN process models produced by pm4py. ⚠️ Please note that BPMN layout generators is still in an **experimental version** and may not produce optimal or visually appealing layouts.
+
+![Application architecture](./architecture/architecture.svg)
+
+## Prerequisites
+
+You can skip this part if your system meets all the requirements listed below 👇
+
+* [Backend requirements](./backend/README.md)
+* [Frontend requirements](./frontend/README.md)
+
+
+## Setup
+* Clone the project in your preferred IDE (e.g. VScode)
+* Prepare the backend environment:
+    1. Navigate to the `backend` folder: `cd backend`
+    2. Create a virtual environment for dependencies called `venv` using the following command: 
+        ```sh 
+          python -m venv venv
+        ```
+    3. Activate the created `venv` by running:
+        * **Windows**: 
+        ```sh 
+          venv\Scripts\activate.bat
+        ```
+        * **Unix/MacOS**:
+        ```sh
+          venv/bin/activate
+        ```
+    4. Install the required libraries listed in `requirements.txt` by running:
+        ```sh
+          pip install -r requirements.txt
+        ```
+* Prepare the frontend environment:
+    1. Navigate to the `frontend` folder: `cd ../frontend` 
+    2. Install the required libraries listed in `package.json` by running:
+    ```sh
+    npm install
+    ```
+## Run
+1. Navigate to the `backend` folder: `cd backend`
+2. Run the application:
+    ```sh
+    python app.py
+    ```
+3. Open a new terminal and navigate to the `frontend`folder: `cd frontend`
+4. Run the development web server: 
+    ```sh
+    npm run dev
+    ```
+5. Access the web application on the displayed localhost: http://localhost:5173/ 

architecture/architecture.svg

@@ -0,0 +1,28 @@
+# Backend requirements
+
+It is assumed that the following is installed on your system:
+
+* `Python 3.6` or higher: https://www.python.org/downloads/
+* `pip`:
+    * **Windows**: The Python installers for Windows include pip. You can make sure that pip is up-to-date by running:
+    ```sh
+    py -m pip install --upgrade pip
+    py -m pip --version
+    ```
+    * **Unix/MacOS**: Debian and most other distributions include a [python-pip](https://packages.debian.org/stable/python/python3-pip) package. You can also install pip yourself to ensure you have the latest version by running:
+    ```sh
+    python3 -m pip install --user --upgrade pip
+    python3 -m pip --version
+    ```
+
+* `venv`: keeps your environments clean by keeping the dependencies in a specific directory for your project. You can install virtualenv by running:
+    * **Windows**:
+    ```sh
+    py -m pip install --user virtualenv
+    ```
+    * **Unix/MacOS**:
+    ```sh
+    python3 -m pip install --user virtualenv
+    ```
+
+* `Graphviz`: pm4py uses Graphviz to encode the structure of process models. It is the only software that needs to be installed on your system from https://graphviz.org/download/. 

backend/README.md

@@ -0,0 +1,43 @@
+# Frontend requirements
+
+You will need [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) to be installed on your system. Node.js `installer` is not recommended, since the Node installation process installs `npm` in a directory with local permissions and can cause permissions errors when you run npm packages globally. Node version manager like [nvm](https://github.com/nvm-sh/nvm) is usually recommended as explained below.
+
+* `nvm`: Node version manager to install `Node.js` and `npm`:
+  * **Windows**:
+    1. Donwload the latest release of [`nvm-windows`](https://github.com/coreybutler/nvm-windows#readme). 
+    2. Click on `.exe` file to install the latest release.
+    3. Complete the installation wizard
+    4. When done, you can confirm that nvm has been installed by running:
+    ```sh
+    nvm -m
+    ```
+  * **Unix/MacOS**: 
+    1. In your terminal, run the nvm installer by using `cURL` or `Wget` commands depending on the command available on your device. These commands will clone the nvm repository to a `~/.nvm` directory on your device:
+    ```sh
+    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
+
+    #or
+
+    wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
+    ```
+    2. Update your profile configuration: Running either of the above commands downloads a script and runs it. The script clones the nvm repository to `~/.nvm`, and attempts to add the source lines from the snippet below to the correct profile file (`~/.bash_profile`, `~/.zshrc`, `~/.profile`, or `~/.bashrc`). If it doesn't automatically add nvm configuration, you can add it yourself to your profile file:
+    ```sh
+    export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" 
+    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
+    ```
+    3. When done, you can confirm that nvm has been installed by running:
+    ```sh
+    command -v nvm
+    ```
+    4. If you run into problems, you can check the [complete documentation](https://github.com/nvm-sh/nvm#installing-and-updating).
+* `Node.js` and `npm`: Use `nvm` to install, and use, the current latest stable version of `Node.js` and `npm` by running: 
+  ```sh
+  nvm install --lts
+  ```
+  Verify it worked by running:
+  ```sh
+  node --version
+  ```
+  ```sh
+  npm --version
+  ```