Skip to content

Commander Spellbook Backend Development Docs

This is the home page of the developer documentation for the Commander Spellbook Backend project.

Architecture

Commander Spellbook consists of three main components:

  • the database, which by default is a PostgreSQL instance
  • the backend, which is a single, self-contained Django project with multiple apps and dependencies
  • the frontend, which is a separate React project that consumes the backend API

Environment Setup for the Backend

You need:

  • Python 3.9 or higher
  • To install the dependencies in requirements.txt using pip install -r requirements.txt
  • pytest and pytest-django for running the unit tests
  • flake8 for linting the code, which is mandatory for contributing otherwise the CI will fail
  • [Optional] VS Code with the Python extension, for development and debugging exploiting the launch.json configuration
  • [Optional] Docker and Docker Compose, for running the entire stack locally
  • [Optional] pip-tools for managing the dependencies, in particular requirements.in is used to generate requirements.txt with the command pip-compile

Branching Model

This page describes the branching model used for the Commander Spellbook Backend project, based on Git.

Trunk based development

It is suggested to follow and contribute to the project using the trunk based development model. Basically, every commit is done on master. This is the simplest model, and it is suggested to use it for small projects.

If a new feature is being developed, a new branch can be created from master, but it is not required. The feature branch name should be prefixed with feature/. When the feature is ready, it can be merged into master, and the feature branch can be deleted.

Semantic versioning and annotated tags

Versioning is done using semantic versioning. Release branches are not allowed. Instead, a new version is created by tagging the commit on master, using a git annotated tag.

When a new version tag is added, it must represent a higher version than any previous tag. The version must be updated according to semantic versioning rules. The tag name must be prefixed with v, and it must be followed by the version number. For example, v1.0.0 is a valid tag name.

Continuous delivery

Whenever a new annotated tag is pushed to the remote repository, the continuous delivery pipeline will be triggered.

Helper scripts

You can download a MIT Licensed semantic version helper script from here and put it in your path. If you do so, you can use the following commands to create a new version tag:

git release major
git release minor
git release patch

Each of these commands will increment the corresponding part of the version number, and create a new annotated tag. In addition to that, it will also sync the current branch with the remote repository, and push the new tag afterwards.

The Minimal Set of Multisets Abstract Data Type

Introduction

The Minimal Set of Multisets (MSM) is a data structure that represents a set of multisets. No multiset in a MSM is a subset of another multiset in the MSM. When you add a new multiset to a MSM, one of two things happens:

  1. If the new multiset is a superset of an existing multiset, nothing happens and the MSM remains unchanged.
  2. Otherwise, if the new multiset is not a superset of any existing multiset, it is added to the MSM. Then, any multiset that is a superset of the added multiset is removed from the MSM.

Example

Suppose we have a MSM with the following multisets:

{1: 1, 2: 1, 3: 2}
{1: 1, 2: 2, 4: 1}
{1: 1, 3: 1, 5: 1}

If we add the multiset {1: 3, 2: 3, 3: 1, 4: 1}, nothing happens and the MSM remains unchanged, because the new multiset is a superset of the second multiset.

If we add the multiset {1: 1, 2: 1, 6: 1}, it is added to the MSM:

{1: 1, 2: 1, 3: 2}
{1: 1, 2: 2, 4: 1}
{1: 1, 3: 1, 5: 1}
{1: 1, 2: 1, 6: 1}

If we add the multiset {1: 1, 2: 2}, it is added to the MSM, and all its supersets are removed:

{1: 1, 2: 1, 3: 2}
{1: 1, 3: 1, 5: 1}
{1: 1, 2: 1, 6: 1}
{1: 1, 2: 2}

If we add the multiset {1: 1, 2: 1}, it is added to the MSM, and all its supersets are removed:

{1: 1, 3: 1, 5: 1}
{1: 1, 2: 1}

Implementation

You can find the implementation of the MSM in the minimal_set_of_multisets.py file.

Nevertheless, the implementation is not optimized for performance. It is intended to be a reference implementation, because the performance of the MSM is not critical for the Commander Spellbook project. If you need a more performant implementation, you can use the reference implementation as a starting point and optimize it for your use case.

These are the papers/links to refer for the implementation of an optimized MSS (Minimal Set of Sets) data structure:

These are the papers/links to refer for the implementation of an optimized MSM (Minimal Set of Multisets) data structure: