This repository contains the code for the software lab "Automatic Conformance Checking Insights in Celonis", offered by the Chair for Process and Data Science at RWTH Aachen University.
- Installation
- Starting the Backend Server
- Starting the Frontend Server
- Contribution Workflow
- Architecture
- Contributors
Note
For an updated installation guide have a look at the hosted documentation.
For installing the project's dependencies, we recommend using uv as it operates very quickly. To install the project's dependencies using uv, follow these steps:
- Ensure that you have uv installed on your system (see here for installation instructions).
- Clone the repository to your local machine.
- Navigate to the root directory of the repository.
- Run
uv sync. uv will then install all necessary dependencies and create a virtual environment in the.venvfolder at the root of the project. - Activate the environment by running
source ./.venv/bin/activateon Mac and Linux, or.venv\Scripts\activateon Windows.
Now you are ready to start.
As a developer, you should also initialize the pre-commit setup. This enforces strict rules when committing to the repository, resulting in a very good code style. There are different hooks that run, which enforce consistent styling and formatting of docstrings and code in general.
After installing the developer dependencies via uv sync, initialize the pre-commit hooks with the command pre-commit install.
After staging the files, when you commit them, all hooks run.
If a hook fails, for example, the ruff hook, because it had to reformat your file, you have to add that file again to the staging area (git add <filename>) and try committing again (git commit).
Notice: The virtual environment has to be activated in order to run all pre-commit hooks.
We recommend this Python styleguide. It mostly complies with the rules enforced by Ruff and with the hooks in the pre-commit setup.
We follow this commit styleguide. It ensures that all commit messages follow the same format and are descriptive and readable.
We should follow this code review styleguide. It ensures that the code review process runs as smoothly as possible.
On the main branch you can start the backend server.
This works if you have installed all dependencies, as well as created a .env file at the root of the directory.
The .env file needs to contain the following entries:
CELONIS_BASE_URL=<your base url>
CELONIS_DATA_POOL_NAME=<a name for the Celonis data pool>
CELONIS_DATA_MODEL_NAME=<a name for the Celonis data model>
API_TOKEN=<your Celonis API token>You can then start the backend server with the command:
uv run uvicorn backend.main:appThis starts the backend server by default on port 8000 on your localhost.
If you navigate to http://127.0.0.1:8000/docs you see the FastAPI Swagger documentation for the endpoints.
Currently there exists only one endpoint to upload an event log, which you can also try via documentation.
To start the frontend server, you have to checkout the frontend-integration branch.
The detailed startup is written in this readme file.
We use a classic feature-branch workflow, where a new branch is created for every feature or bug fix. Then a pull request is opened, which is then merged into the main branch of the project. In addition to that, the main branch is protected, so there cannot be any commits to it directly, which enforces the above-described workflow.
Note
For an updated architecture diagram, have a look at the hosted documentation.
Below is an architecture suggestion, with which we can start out if all team members agree on it.
The following people have contributed on this project: