[](https://)# Whiteboard PoC: Technical notes and design options

For whiteboard inclusion in Alkemio, we settled on Excalidraw. This is an open source solution with plenty of integration options. Its main drawback is that it does not currently allow images to be included.

There's three ways to integrate Excalidraw:

- Using excalidraw.com
- Self-hosting an excalidraw.com deployment
- Integration within the website.

The first option has a PoC here: https://github.com/alkem-io/client-web/tree/whiteboard-806

In the end, we decided to go with the third option because it allows the best integration with the Alkemio platform. I.e. we can listen to changes on the whiteboard and use those to update the domain model, and vice versa. The PoC for the embedded version is here: https://github.com/alkem-io/client-web/tree/whiteboard-806-embedded

The API for the Excalidraw component is documented in the [npm README](https://www.npmjs.com/package/@excalidraw/excalidraw).

Couple of gotcha's:

- `excalidraw.refresh()` needs to be called whenever the whiteboard moves on the page (currently on scroll)
- `onExportToBackend` is wrongly documented as `exportToBackend` [PR for fix](https://github.com/excalidraw/excalidraw/pull/3952)

Current functionality of PoC:

- Whiteboard contents are saved to Ecosystemmodel
- Whiteboard contents are loaded from backend on pageload (using `intialElements` parameter)
- Can create new actor with link to domain model
- Changing the text in the whiteboard will change domain model

Currently unimplemented/buggy:
- Changing the domain model will not update the whiteboard
- Loading the whiteboard from the backend will break the "whiteboard link to domain model functionality"
- Don't know how to do horizontal scroll on whiteboard, don't know if it's needed. Currently vertical scroll works with scrollwheel.

Implementation details:

- Whiteboard load/unload is implemented by just serializing all the contents and saving them into the database as seralized json (DB change done by Neil to make this a json field in the database).
- Link between domain modal and whiteboard is done by keeping track of identifiers of elements and corresponding actors in the `identifierMap`
- Templates used for actor were created by just importing a library element and exporting that using excalidraw.com.

Design/UX considerations:
- The actor inserted is part of a group (using `groupIds`), but this group can be broken up. This can have weird implications, where a user could change a textfield that just looks generic to them that is coupled to the domain model. Maybe use some special formatting for these text fields?
- Keeping track of where there's content can be a little wacky. If you use the `refresh()` API to update the relative location of the whiteboard it shouldn't be too bad, but there's still some issues where content sometimes disappears. Maybe add some sort of bounding box and always focus on that?
- Currently, the whiteboard is in edit-mode for everyone. Users that aren't allowed to update the ecosystem model also shouldn't be allowed to update the whiteboard. Either put whiteboard in view-only mode (property `viewModeEnabled`), or communicate that doodling is not saved. Alternatively you could save in localstorage, but this is going to cause some asymmetry in what people see.

Technical future considerations:
- Live collaboration is not working currently. [Implementation example used for excalidraw.com](https://github.com/excalidraw/excalidraw/blob/master/src/excalidraw-app/index.tsx). It looks like they're syncing the entire array of elements up, and since there's end-to-end encryption, I don't think they're doing anything fancy on the server. If we were to introduce images somehow, if base64-encoded, rather than linked, it might make this approach infeasible.
- There's different ways to introduce templates into the whiteboard. For static templates, we should probably just fill the `libraryItems` prop, which will put them in the library to be used. Dynamic items could also be put in the library, as long as the dynamic parts are unambiguous. (i.e. "Title of the Opportunity", which changes the same way the actor name does.). In such a case, we could listen to this element being added to the whiteboard and then replacing a template text with the synced version.