eclipse-score · LittleHuba · Jun 6, 2025 · Apr 29, 2025 · Jun 5, 2025 · Jun 6, 2025
@@ -0,0 +1,144 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+.. _com_architecture:
+
+Architecture
+============
+
+Overview
+--------
+
+An brief overview of communication is described :ref:`here <com_abstract>`.
+
+Description
+-----------
+
+A description of the communication module is located :ref:`here <com_rationale>`
+
+.. _com_static_architecture:
+
+Static Architecture
+-------------------
+
+As discussed in :ref:`com_rationale`, the overall architecture of the communication framework must be layered. This is required, to separate the frontend from the underlying communication mechanisms (also called bindings).
+
+This ensures a stable public API, independent of the underlying binding(s). At the same time, the communication framework can support many different communication protocols in a flexible manner.
+
+.. feat_arc_sta:: Feature Architecture Communication
+   :id: feat_arc_sta__com__communication
+   :security: YES
+   :safety:  ASIL_B
+   :status: valid
+   :fulfils: feat_req__com__interfaces
+   :includes: logic_arc_int__communication__user
+
+   .. needarch::
+      :scale: 50
+      :align: center
+
+      {{ draw_feature(need(), needs) }}
+      mod_view_sta__tracing__tracing -[hidden]-> mod_view_sta__baselibs__baselibs
+
+In the following sections we will look on the different architectural elements of the communication framework in more
+detail.
+
+Frontend
+^^^^^^^^
+
+The frontend is responsible of providing a stable public API to the user. In general, the communication framework (`mw::com`) follows the client-server, pub-sub and producer-consumer patterns.
+
+Following these patterns, the user interacts with different APIs depending on whether he is producer/server or
+consumer/client.
+
+A producer creates a `Skeleton` to communicate with consumers. Each consumer creates a `Proxy` to connect to a producer. Consumers can find available producers through a service discovery mechanism. This mechanism is tightly bound to the `Proxy`, to only discover producers offering a compatible implementation of a `Skeleton`.
+
+.. uml::
+    :scale: 50
+    :align: center
+    :name: doc__communication__proxy_skeleton
+    :caption: Communication through mw::com
+
+    package "Consumer" <<Rectangle>> {
+        package "Frontend" <<Frame>> #D5E8D4 {
+        object "Proxy" as proxy_t
+        }
+        package "Binding" <<Frame>> #DAE8FC {
+        object "Proxy" as proxy_b
+        }
+    }
+
+    package "Producer" <<Rectangle>>  {
+        package "Frontend" <<Frame>> #D5E8D4 {
+        object "Skeleton" as skeleton_t
+        }
+        package "Binding" <<Frame>> #DAE8FC {
+        object "Skeleton" as skeleton_b
+        }
+    }
+
+    skeleton_t -d-> skeleton_b
+    proxy_t -d-> proxy_b
+    proxy_b -l(0- skeleton_b
+
+In addition to these elements, a runtime singleton is used for background tasks to reduce resource consumption. This runtime is invisible to the user. This runtime is responsible for service discovery (explained in :ref:`ipc_service_discovery`), notification reception and other infrastructure tasks.
+
+Compatibility of *Skeleton* and *Proxy* is currently defined by them sharing the same communication interface. Additionally, versioning will be taken into account in the future (see :ref:`ipc_roadmap`).
+
+The communication interface for now consists of events. Support for methods and signals will be added in the future
+(see :ref:`ipc_roadmap`).
+
+Since S-CORE supports strongly typed programming languages, the API of *Skeleton* and *Proxy* is also strongly typed. Instead of a code generator, we utilize features like templates in C++ and macros in Rust to "generate" the necessary code at compile time.
+
+But there are some "niche" use cases, where the need to "regenerate" and recompile the *Proxy* can be detrimental.
+This is the case when:
+
+- signatures are trivial and changes/differences between them are minimal
+- the communicated data/payload gets handled very generically (loosely typed) anyhow
+- the communicated data/payload has to get deep-inspected based on additional/separate type-information anyhow
+
+For these cases *mw::com* provides a *GenericProxy* that allows introspection of communication interfaces at runtime.
+
+While the frontend is based on a communication model, it is independent from any communication protocol. Therefore, it always forwards user requests to the binding(s) underneath. Which bindings to use is defined in a configuration file.
+
+A multi-binding approach is chosen, where API calls are mapped to a set of selected bindings.
+
+Interface Description
+^^^^^^^^^^^^^^^^^^^^^
+
+The public API for the frontend is defined as:
+
+.. logic_arc_int:: Communication User Interface
+   :id: logic_arc_int__communication__user
+   :security: YES
+   :safety: ASIL_B
+   :status: valid
+   :fulfils: feat_req__com__interfaces
+
+   .. needarch::
+      :scale: 50
+      :align: center
+
+      {{ draw_interface(need(), needs) }}
+
+Bindings
+^^^^^^^^
+
+The need for bindings was discussed in :ref:`com_multi_binding_support`.
+Bindings reside beneath the frontend layer and accept the forwarded requests
+
+Currently, the available bindings are:
+
+- :ref:`IPC (LoLa) <communication_ipc>`
+- :ref:`mock binding <mock_binding>`