Review the Concepts Reference Draft

[emanuelpalm]

The Arrowhead community is admonished to read and review the latest Concepts Reference draft, available in the documentation repository.

Please read the document via the below link, and then create Issues with any comments you may have in the documentation repository. Please start the titles of your issues with Concepts Reference:. Alternatively, you may elect to post your comments in this issue.

https://github.com/eclipse-arrowhead/documentation/blob/master/distribution/Eclipse%20Arrowhead%20Concepts%20Reference%20v0.3.Proposal.pdf

[emanuelpalm]

This is my summary of the review we are conducting internally at Sinetiq. @jerkerdelsing @jenseliasson @palvarga @PerOlofsson-Sinetiq @henrikbylund @MatsBJohansson

Review Summary

General

1. A separate document should exist that addresses the differences between Arrowhead and other concept domains, such as microservices architecture or old-style SOA (ESB, SOAP, etc.).

Section 2.3 Service Provision and Consumption

1. The sentence "Systems may provide services, which other systems can consume by sending messages to their operations [...]" makes it seem as if the request-response paradigm is mandatory.
2. Service provision cannot be defined in terms of the direction of request messages.

Section 2.4 System Composition

1. Deemphasize "the cloud". This document should not be about "the cloud" or the cloud computing paradigm.
2. Arrowhead-compliance for clouds is not defined yet, but is claimed to be a thing in footnote 2.

Section 3.3 Device

1. How about virtual devices?
   • The definition has been widened in version 0.3 of the document to also include virtual devices.

Section 3.4 System

1. The terms Systems and Services are preferred over Microsystems and Microservices.
2. Systems are providers and consumers of services.
   • Should we deemphasize the term System and instead pivot towards Prosumer? Can both terms coexist?

Section 3.5 Service

1. The section makes it seem as if the request-response communication paradigm is mandatory. It should be clear that any paradigm is acceptable.
2. "[...] by every message being required to ~stating~ state what exact operation [...]".
3. Service type identifiers, or just service types, are rather crucial to how services are addressed. They should be defined in more detailed in this document.

Section 3.6 Operation

1. Make it more clear that operations accept entire messages, including metadata about any payload those messages may contain.

Section 3.8 Cloud

1. What is a Cloud?
   • There seems yet to be consensus on the exact definition of the term.
   • The current proposal is "an identifiable system-of-systems with at least one boundary".
     • The definition makes it possible to talk about virtual and local clouds, as well as public (publically accessible (on the Internet?)) and private ones.
     • How do we talk about clouds that are interconnected? Bridged clouds? Are there different kinds of bridges? Is this out of scope?
     • The definition in the glossary is inaccurate.
2. "[...] border systems. I[t] must be possible for every [...]".

Section 3.9 System-of-Clouds

1. Can a system-of-clouds be a component of a larger structure, or is at the top of the abstraction hierarchy?

Section 3.10 Network

1. Why is this part of the Concepts Reference at all? Network equipment is supporting infrastructure. Does it have to be at the center of Arrowhead?

Section 3.15 Profile

1. The text is confusing. Can it be made more clear what a profile is?

[emanuelpalm]

I will be addressing the above comments in the coming weeks. Several of them will require further discussions, however, in order for me to be able to do anything else than try to clarity the existing text.

[jenseliasson]

This is a most welcome initiative!

Good job!