Added ADR for shell api

architecture/adr-016-shell-api.md

@@ -0,0 +1,50 @@
+<!-- Morgan Stanley makes this available to you under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. See the NOTICE file distributed with this work for additional information regarding copyright ownership. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
+
+| Type          | ID            | Status        | Title                   |
+| ------------- | ------------- | ------------- | ----------------------- |
+| ADR           | adr-016       | Approved      | Shell API               |
+
+# Architecture Decision Record: Shell API
+
+## Context
+
+We must ensure apps written for Compose UI can run in any shell implementation and provide a consistent developer experience across shells. In order to achieve this, a fixed set of features for shell interaction need to be defined and made available for developers.
+
+Another consideration we must make is how easy is it to bring existing applications into the ComposeUI environment. "Basic" web apps are expected to run out of the box, but apps targeted at running inside containers might leverage specific APIs. We need to consider API compatibility with other desktop containers as well as DesktopJS, an abstraction layer over multiple web container APIs we are maintaining.
+
+A list of features we want to provide with high priority:
+ - Window management
+ - Notifications
+ - Registering global hotkeys
+ - IPC
+ - (Remote) logging
+
+## Decision
+We will implement the DesktopJS API as the base of our shell API.
+
+The DesktopJS API is an abstraction layer above multiple desktop container technologies, already adopted by projects. Implementing it as part of the shell API enables applications targeting DesktopJS to run in ComposeUI without modifications necessary in the apps or DesktopJS.
+
+The DesktopJS interface covers the following features we prioritize:
+ - Window management
+ - Notifications
+ - Global hotkeys
+ - IPC (We prefer FDC3 as the IPC interface, but the MessageRouter can be used directly and calling it via DesktopJS is trivial to implement)
+ - Logging
+
+It covers further features we need to consider how to implement:
+ - Layout management (While this is a desired feature on the container level, saving specific module state is not in the initial feature set and will need future consideration)
+ - Adding a tray icon
+ - Screen info
+
+## Alternatives considered 
+
+### Implementing the API of another desktop container
+This option sounds promising as applications targeted to that specific API would run in ComposeUI by default.
+This would introduce a dependency on the development of an external interface - something that happens quite often, and breaking changes are not unheard of.
+A further drawback is that we would force users of other containers to essentially port their apps to another container, something we consider undesirable compared to promoting the freedom of adopting DesktopJS.
+
+### Designing our own API
+The benefit of this option is that we would have the most control over our API but adoption by app developers is still an issue and designing a new API from scratch is a lot of unnecessary work. It would also impose work on implementing a DesktopJS adapter - a project maintained by us.
+
+## Consequences
+We need to review priority of implementing the additional features covered by DesktopJS. When considering additional features not covered by DesktopJS, contributing to the DesktopJS project can be considered.