# Cherrytwist Domain Model + api
This document is aimed at creating a shared roadmap for:
* The Cherrytwist logical domain model
* The api that allows clients to interact with that domain model

## Considerations
Key considerations for the domain model roadmap:
* **Flexibility**: the ways in which collaborations take place are many and varied, and the domain model should be flexible to support many patterns for all aspects (i.e. Context, Community, Collaboration)
* **Simplicity**: the domain model should be simple enough for end users to understand, using familiar concepts where feasible

Key considerations for the api roadmap:
* **Minimisation of # api calls**: Usage of interfaces where possible to avoid an explosion of api calls / types
* **Strong typing** (where feasible): Balancing strong typing with flexibility
* **Maintainability**: the api should allow for ease of upgrading, especially given plans for SaaS.

## Current status
The current Cherrytwist domain model is very simple, and can is highly shaped by the collaboration model used by Odyssey at their Momentum event in November 2020.

Strong points:
* Clear concepts of Context and Community
* Best practices from experience on journey so far being applied to step up the future extensibility

Weak points
* **Rigid / Not rich enough**: No extensibility support for key entities such as Context. Using the Context example, this currently has 5 hard coded fields - which would not vbe rich enough for supporting multiple deployments.
* **Duplication**: Clear overlap in concepts e.g. Ecoverse / Challenge / Opportunity. Affects both conceptual model and api (as well of course as code base / maintenance).
* **Identifiers**: are local to each type, precluding practical usage of interfaces
* **Authorisation**: currently suitable for a single Ecoverse, needs to be revisited when support multiple ecoverses. Also needs to be expanded to connect with notion of Lifecycle as well as operation in a decentralised environment (SSI / Verified Credentials)
* **Collaboration aspect not yet developed**: Of the three core aspects, Collaboration one has received the least attention. Logical enough given that Collaboration depends on Context and Community to be effective. Key current entities:
* Relation: basic design, driven by design of Momentum.Needs significant additional design work.
* Projects: for now just placeholders - albeit an area with huge potential.

In addition there are several key enhancements in the pipeline:
* **Lifecycle management**: an initial PoC is being worked, which looks immensely powerful + elegant. Further integration and design work is required, but may not be that far from being ready for production usage.
* **Agents / decentralisation**: also at the prototype state, and has a longer runway to being ready for production usage.

This document is intended as a working document to capture ideas and concepts that we can use to refine / expand both the domain model and api in a wider context.

# Domain model refinements

## Collaboration Entity
This would be a new core element of a Challenge, and would for now have the following entities within it:
* Relation
* Project

A Challenge could choose to have an empty Collaboration instance.


## Challenges Hierarchy
The concepts of Ecoverse, Challenge and Opportunity are extremely similar. This is clear when looking at the code for these three entities.

Proposed path forward:
* **Challenge entity with child challenges**: the Challenge entity has notions of context, community and collaboration - and critically can also have child challenges.

This maps to our current conceptual design as follows:
* Ecoverse ==> Root level entities within the platform, can have child challenges. Note: implementation wise the Ecoverse simply delegates to single Challenge entity that it contains.
* Challenge ==> Challenge with child challenges.
* Opportunity ==> Challenge without child challenges.

With this model we could default to the hierarchy as it is currently, but also support simpler / more complex hierarchies.


### Challenge Glossary

Using PMP [Project Management Glossary](https://www.smartsheet.com/complete-glossary-project-management-terminology):

* [Challenge](https://dictionary.cambridge.org/dictionary/english/challenge) - something that needs great mental or physical effort in order to be done successfully and therefore tests a person's ability.
* Project - A temporary, goal-driven effort to create a unique output. A project has clearly defined phases, and its success is measured by whether it meets its stated objectives.
* Opportunity - In project management, an opportunity is a possibility that can contribute to project objectives. Opportunities in project management are classified as a type of risk. Opposed to
* Threat - A negative risk that could adversely affect project objectives.

## Context Extensibility
The Context for a Challenge will vary depending on the actual deployment use case. As such the platform needs to be able to support extensions to the information that is stored and managed by the platform for Contexts.

The envisaged path forward for this would be the following:
* **Context Interface**: defines a core set of information that all Context entities need to provide
* ***Base Context*** implementation: implements Context interface and not much more. This is likely analagous to the existing Context object
* ***Extended Context*** implementation: extends the base Context class with additional domain model entities.

Note: the names above are for now mainly to convey the concept.

### Context Modules
The extension of the entities stores within the context should be modular. In particular the following modules could be envisaged:
* **Framing**: sets the background, vision, for whom etc
* **Legal**: the terms that are applicable for the Challenge
* **Ecosystem Model**: manages multiple sets of actors into actor groups
* **Considerations**: that manages a set of Aspects

Mapping to our current situation:
* Current Context entity ==> Base Context
* Opportunity Context (= current Context + Actor Groups + Aspects) ==> Extended Context entity.


## Community Extensibility
A similar pattern to the above can be envisaged for the Community entity.

The information contained within such an implementation is to be determined.

## Collaboration Extensibility
A similar pattern to the above can be envisaged for the Collaboration entity.

The information contained within such an implementation is to be determined.

## Templates
The choice of which actual Context / Community implementation to use should, for now, be made at the moment the Ecoverse is instantiated.

This instantiation should take a configuration file that specifies:
* The number of levels
* For each level the type of Context to be used, as well as any configuration of the Community implementation (e.g. groups / roles to be used)

### Templates Definition
The definition of templates needs to be clearly designed into the logical domain model.

In particular, when creating any extensible entity (e.g. Context, Community, Collaboration) the creation DTO should include the template to be used. This template information could be determined by the parent of the entity being created, but could also be a choice at time of instantiation.

Initially it is likely the platform will support two templates to demonstrate / ensure the flexibility - with the goal of supporting more later.

### Defined by the platform
Initially the set of templates is defined by the platform. It is likely a later exercise to allow a custom extensibility framework.

### Lifecycle Template
Similar to the choice of Context type, at the point of instantiation a particular Lifecycle can be chosen.

## Relation Entity
This entity conceptually should be about tracking collaboration within the context of a Challenge. This is not the current implementation.

# API Roadmap
The current api was created under tight deadlines in 2020, and significant effort has gone into refining that api in 2021.

In addition to the changes implied by the domain model updates described above, there are also multiple generic aspects of the api that can be improved.

## Global Identifiers
All identifiers are currently unique within the entity type i.e. all users have a unique identity, but groups / challenges etc could have the same value. This is not conducive to a flexible api, whereby multiple objects could be implementing a given interface type.

The goal is to move to a globally unique identifier for all entities within the domain model

## Scalar types
The api at the moment does not use custom scalar types.

Candidate scalar types:
* **ID**: for uuids representing entities
* **TextID**: for textual identification of an entity within a given context (Currently called TextID)
* **Markdown**: for fields that contain Markdown

It is worth considering to use a wider set of Scalar types in the api, not least to convey to clients of the api key restrictions of each type e.g. length of allowed text, format of TextID. This would then move responsibility for validation directly to the Graphql type system.

## Markdown for content
The api currently only stores simple text for fields that are used by the client for displaying content to end users.

In light of the desire to give users more control over how content is displayed, it is worth considering switching some of the text fields to be designated as containing Markdown.

This could be combined with the above mentioned expansion of the set of Scalar types used by the platform.

## Pagination
The api allows for the retrieval of all entities of a given type, in particular Users. This has clear performance implications as the number of Users of the system expands.

A well known pattern for supporting pagination of entities via GraphQL is the [Connection pattern](https://relay.dev/graphql/connections.htm).

## Misc design issues to be addressed
Tagsets on user profiles: current associated with Ecoverse template definition but that does not work once have multiple ecoverses.

## Remove fine grained mutations not required
The following mutations are not required as the updates happen via the parent entity update
* updateReference(updateData: UpdateReferenceInput!): Reference!
* updateTagset(tagsetData: UpdateTagsetInput!): Tagset!