# Collaboration using Canvases

The current Alkemio platform is very much focused on managing the **definition of where** the collaborating parties wish to do, as well as **managing the community** that is engaged. There is also some emerging communication capabilities (Updates, Discussions).

However users also need to be **able to work together i.e. Collaborate**. The first capability to be added to support this is being able to create and share whiteboards. In Alkemio a whiteboard is referred to as a Canvas.

As such the *key driver* and critical value to be realized near term is to show that it is possible to create and manage Canvases directly within the context of a Challenge, ideally from Templates. This brings the following benefits:
* Users are **able to do something** creative in the platform
* The message about **sharing best practices** becomes very tangible and credible

As such the near term focus has to be on a quick integration of the Canvases into the platform, including global templates support.

Terminology: this document talks about the usage of Canvases for Challenges, but this should be read as also making Canvases available for Hubs and Challenges where they are equally relevant and available.

## Design notes
A canvas is a creative, unstructured place for user collaboration. This is a nice complement to the highly structured domain model. And there is also the possibility to integrate the two, by having a visual entity in a canvas being linked to an entity in the domain model e.g. an Actor in an EcosystemModel.

There are multiple applications for canvases in Alkemio, roughly in order of likely platform support:
* generic creative whiteboard: just a blank sheet that users can fill in together
* instantiate from a template: this allows methodologies to be available to users
* support creating an ecosystem model: this involves integrating the unstructured canvas with the structured domain model.

### Methologies / Best Practices
For the methodologies there are clear examples from Digicampus that should be relatively straightforward to support:

### Ecosystem Modeling
For the EcosystemModel use case, the ultimate goal looks something like the following:

However this capability is further out than the first two use cases. There is additional information related to Ecosystem Modeling in general later in this document.

## Technology: Excalidraw
The selected component for implementing Canvases in Alkemio is [Excalidraw](https://excalidraw.com/).

This component was selected for the following reasons:
* Open source and a compatible license
* Active and rapidly growing community
* Both standalone components and real time collaboration options available
* Support for templates / libraries of visual artifacts
* Implementation is using a similar tech stack to Alkemio

Note that Excalidraw has multiple components in their architecture:
* Standalone client side component for working with / editing a Canvas
* Server to faciliate real time collaboration on a Canvas
* Online service where users can create and work with Canvases

For Alkemio one key driver is that data is stored where feasible within the context of the Challenge, so the Canvas data will be stored within the domain model. This is feasible as the data is relatively small, as (for now) the storing of large data objects such as images is not supported by Excalidraw.

Note that there has already been good (technical) interaction with the Excalidraw community.

### Example 1: Flow charts
Example usages of Excalidraw are shown below:


### xplainers
An explanation of XState in Excalidraw:


## Status

The following investigations have already been done:
* Domain model entity added for Canvas, with a single instance then being available on each EcosystemModel
* The Excallidraw component has been integrated directly into the web client
* The options for linking the domain model with the visual entities has been investigated and a small PoC created to demonstrate how this coudl work
* A demonstrator of doing real time collaboration using the hosted Excalidraw service was created (requires Excalidraw server for working)

## Phasing
One possible phasing is as follows:
1. Allow single user creation and editing of blank Canvas entities per Hub / Challenge / Opportunity
2. Allow the instantiation of a Canvas from a Template, with the platform offering initially global templates.
* A follow up step would be to allow per Hub temmplates.
* The instantiation could also allow references e.g. to the Hub/Challenge/Opportunity name / tagline etc as a one off population translation.
3. Allow creation of EcosystemModels via a Canvas, with direct linking to the structured domain model.
* The EcosystemModel would then be able to "listen" for new Actor created events, and / or allow the creation of Actors directly from within the Domain model
4. Allow real time collaboration on Canvases
* Requires the Excalidraw server to be available in our cluster and accessible likely directly (i.e. not via api)

## Work packs (phase 1)
* Refine the domain model: allow multiple Canvas entities to be stored on the Context entity. Also allow each Canvas entity to have a Title and a Description, as well as other meta-data such as created date, last edited date, created by etc.
* Mockup for how the user would interact with Canvases, including how the "lock" a canvas for editing and how a user selects a Template to base the Canvas on
* Creation of one or more "Templates" that can be used to instantiate a Canvas.
* Demonstrator for how to instantiate a Canvas using a custom template.
* Design for how we are going to manage Templates, initially globally but also later per Hub.

## Open questions / risks
* How do we deal with simultaneous editing of canvases? Does a canvas get "checked out" for editing?
* _This is actually a much more general question as we start allowing actual collaboration on the platform. In general how to we manage who is working on what artifact at any one time?_
* What is the authorization model around canvases? Who can create them (any member?)? Who can edit?
* How to manage templates? And how to allow custom templates e.g. at the Hub level?
* What are the implications for supporting the real time shared editing via an Excallidraw server that is part of our cluster?
* How do we deal with history and multiple edits? Does Excallidraw have a history function?

## Ecosystem Modeling
For the EcosystemModeling there needs to be further investigation done into modeling frameworks / communities.

Key relevant communities include:
* TokenEngineering: originating in Berlin but also an active local community in Amsterdam
* ValueEngineers: seems to be a new initiative originating in VUE (Amsterdam), they are engaging with 2Tokens.


* In addition the field of SystemMapping seems to be emerging.