docs: add domain model documentation (eclipse-edc#761)

* Docs: Create domain-model documentation and correct link in README.md

* Docs: Add Information into README.md and reestructure domain-model.md

* Docs: Remove unused diagram

* Docs: Add Domain model diagram

* Docs: Modify diagram, make review corrections

* Docs: Add modified diagram

* Docs: Remove HTML Tags

* Docs: Modify Domain Model Diagram

* Docs: Improve descriptions of components in domain model diagram

* Docs: Make corrections based on reviews.

* Docs: Reformat titles and local Links into domain-model.md.

* Docs: Mark Class objects inside the document based on the review.

* Docs: Mark Class objects inside the document based on the review.

* Correct some definitions related to the domain-model document.

* Add changes in Changelog related to documentation

* Move documentation feature to section Unreleased

* Move documentation feature to section Unreleased

CHANGELOG.md

@@ -1,12 +1,11 @@
-
 # Changelog
 
 All notable changes to this project will be documented in this file - formatted and maintained according to the rules
 documented on <http://keepachangelog.com>.
 
-This file will not cover changes about documentation, code clean-up, samples, or the CI pipeline. With each version 
-(respectively milestone), the core features are highlighted. Relevant changes to existing implementations can be found in
-the detailed section referring to by linking pull requests or issues.
+This file will not cover changes about documentation, code clean-up, samples, or the CI pipeline. With each version
+(respectively milestone), the core features are highlighted. Relevant changes to existing implementations can be found
+in the detailed section referring to by linking pull requests or issues.
 
 ## [Unreleased]
 
@@ -18,7 +17,7 @@ the detailed section referring to by linking pull requests or issues.
 
 #### Added
 
-*
+* Add domain model documentation (#1158)
 
 #### Changed
 
@@ -115,6 +114,7 @@ the detailed section referring to by linking pull requests or issues.
 * Update CI workflow to use concurrency (#1092)
 * Adapt system-test to use Embedded DPF to perform file copy (#1060)
 * Remove default token-based authentication at the DataManagement API (#981)
+*
 
 #### Removed
 

docs/README.md

@@ -27,10 +27,13 @@ TBD
 TBD
 
 ## Architecture
-[Architecture Principles](docs/architecture-principles.md)
 
-[Sequence diagrams](architecture/README.md)
+[Architecture Principles](architecture-principles.md)
+
+[Sequence Diagrams](architecture/README.md)
+
+[Domain Model](domain-model.md)
 
 ## Terminology
 
-TBD
+see [Terminology](Terminology.md)

docs/diagrams/domain-model.puml

@@ -0,0 +1,87 @@
+@startuml
+'https://plantuml.com/object-diagram
+
+skinParam NoteBackgroundColor WhiteSmoke
+skinParam NoteFontColor Black
+skinParam ParticipantBackgroundColor WhiteSmoke
+skinParam ActorBackgroundColor WhiteSmoke
+skinParam AgentBackgroundColor White
+skinParam AgentBorderColor SkyBlue
+skinparam shadowing false
+
+object "Policy" as policy {
+  Technically processable contract.
+  Based on the ODRL.
+  --Contains--
+  * Permitions
+  * Prohibitions
+  * Duties
+
+}
+
+object "Contract Offer" as contract_offer{
+   Dynamically generated and \nnot persisted anywhere.
+   --Contains--
+   * Asset
+   * Policy
+}
+
+object "Contract Negotiation" as contractNegotiation{
+    Represent the negotiation process.
+    --Contains--
+    * Final contract agreement
+    * Contract offers
+}
+
+object "Contract Agreement" as contractAgreement{
+    Describes the signedcontract\nbetween the consumer and provider.
+    --Contains--
+    * Asset
+    * Policy
+}
+
+object "Resource" as resource{
+    Describes resources of the data transfer.
+}
+
+object "Asset" as asset{
+    Describes data which should be transferred.
+}
+
+object "Contract Definition" as contractDefinition{
+    Template for contract offers.
+    --Contains--
+    * Access Policy
+    * Contract Policy
+    * Asset selector
+}
+
+object "Data Address" as dataAddress{
+    Describes datasource for Asset-Data.
+}
+
+object "Data Request" as dataRequest{
+    -- Contains --
+    * AssetID
+    * ContractID
+    * dataDestination
+}
+
+object "Transfer Process" as transferProcess{
+    Runs through a state machine.
+    Symbolizes the data transfer on the control plane.
+}
+
+contractDefinition --> policy: Contains
+contractDefinition --> asset: Selects (0..*) \nvia AssetSelector
+contract_offer --> contractAgreement: Transferred into\n(after the agreement)
+asset --> dataAddress: Describes where the\ndata comes from
+contractDefinition --> contract_offer: Generates x \n contract offers
+contractNegotiation --> contractAgreement: Contains the\nfinal agreement
+transferProcess --> resource: Provisions,\ntransfers,\nand deprovisions
+transferProcess --> dataRequest: Contains
+dataRequest --> dataAddress: Describes where the\ndata should be copied
+contractNegotiation --> contract_offer: Contains history of\nseveral offers
+
+@enduml
+

docs/domain-model.md

@@ -0,0 +1,63 @@
+# Domain Model
+
+![domain-model](diagrams/domain-model.png)
+> The shown picture illustrates only a generic view of the Domain Model and is not intended to show all aspects of the project.
+
+## Asset
+
+An asset represents data (databases, files, cache information, etc.) which should be published and shared between
+organizations. For each asset, a [`DataAddress`](#data-address) needs to be resolvable.
+
+## Data address
+
+A data address is a pointer into the physical storage location where an asset will be stored
+
+## Contract
+
+A contract always contains one or more [`Assets`](#asset) and a single [`Policy`](#policy). The contract construct is
+used to define the arrangement between two parties ("consumer" and "provider"). Regarding this arrangement, the contract
+passes several stages which are explained below:
+
+* ### Contract definition
+
+  Contract definitions associate a policy with assets. A `ContractDefinition` object contains access policies, contract
+  policies, and an asset selector which links the contract to one or more assets.
+
+* ### Contract offer
+
+  The contract offer is a dynamic representation of the [`ContractDefinition`](#contract-definition)
+  for a specific consumer and serves as protocol's data transfer object (DTO) for a particular contract negotiation.
+  Contract offers are not persisted and will be regenerated on every request. The connector acting as data provider will
+  generate contract offers only for contract definitions dedicated to the organization or data space participant
+  operating the requesting connector acting as data consumer. A contract offer is always related to a single asset of
+  the `ContractDefinition` object (e.g. for a `ContractDefinition` containing three `Asset` objects, the connector will
+  generate three `ContractOffer` objects)
+  .
+
+* ### Contract negotiation
+
+  A `ContractNegotiation` captures the current state of the negotiation of a contract (`ContractOffer` ->
+  `ContractAgreement`) between two parties. This process is inherently asynchronous, so the `ContractNegotiation`
+  objects are stored in a backing data store (`ContractNegotiationStore`).
+
+* ### Contract agreement
+
+  A contract agreement represents the agreed-upon terms of access and usage of an asset's data between two data space
+  participants, including a start and an end date and further relevant information.
+
+## Policy
+
+Contract policies represent permitted and prohibited actions over a certain asset. These actions can be limited further
+by constraints (temporal or spatial) and duties ("e.g. deletion of the data after 30 days"). Further information is
+provided in a separate [section](Policies.md).
+
+## Data request
+
+After a successful contract negotiation, a `DataRequest` is sent from a consumer connector to a provider connector to
+initiate the data transfer. It references the requested [`Asset`](#asset) and [`ContractAgreement`](#contract-agreement)
+as well as information about the [data destination](#data-address).
+
+## Transfer process
+
+Similar to the `ContractNegotiation`, this object captures the current state of a data transfer. This process is
+inherently asynchronous, so the `TransferProcess` objects are stored in a backing data store (`TransferProcessStore`).