Fix top-level documentation

README.md

@@ -1,118 +1,47 @@
 
-# C++ & Rust Bazel Template Repository
+# Logging
 
-This repository serves as a **template** for setting up **C++ and Rust projects** using **Bazel**.
-It provides a **standardized project structure**, ensuring best practices for:
+This module provides components (`mw::log`, `datarouter`, `score_log_bridge`) for
+safety-critical logging (Diagnostic Log and Trace) in embedded automotive systems.
 
-- **Build configuration** with Bazel.
-- **Testing** (unit and integration tests).
-- **Documentation** setup.
-- **CI/CD workflows**.
-- **Development environment** configuration.
-
----
-
-## 📂 Project Structure
-
-| File/Folder                         | Description                                       |
-| ----------------------------------- | ------------------------------------------------- |
-| `README.md`                         | Short description & build instructions            |
-| `score/`                            | Source files for the module                       |
-| `tests/`                            | Unit tests (UT) and integration tests (IT)        |
-| `examples/`                         | Example files used for guidance                   |
-| `docs/`                             | Documentation (Doxygen for C++ / mdBook for Rust) |
-| `.github/workflows/`                | CI/CD pipelines                                   |
-| `.vscode/`                          | Recommended VS Code settings                      |
-| `.bazelrc`, `MODULE.bazel`, `BUILD` | Bazel configuration & settings                    |
-| `project_config.bzl`                | Project-specific metadata for Bazel macros        |
-| `LICENSE.md`                        | Licensing information                             |
-| `CONTRIBUTION.md`                   | Contribution guidelines                           |
+See the [module documentation](docs/index.rst) for the full overview, repository layout, and component
+architecture.
 
 ---
 
 ## 🚀 Getting Started
 
-### 1️⃣ Clone the Repository
-
-```sh
-git clone https://github.com/eclipse-score/YOUR_PROJECT.git
-cd YOUR_PROJECT
-```
+### 2️⃣ Build & Run Tests
 
-### 2️⃣ Build the Examples of module
+See the [Quick Start](docs/index.rst) section of the module documentation for the exact `bazel build`/
+`bazel test` commands (including the platform `--config` and `--test_tag_filters` needed to select
+unit, component, or QNX/QEMU integration tests).
 
-> DISCLAIMER: Depending what module implements, it's possible that different
-> configuration flags needs to be set on command line.
+> TIP: For a single release-artifact target, provide a `:release_artifacts` filegroup per module
+> (e.g. `bazel build //score/<module_name>:release_artifacts`) — final decision is up to the module
+> maintainer.
 
-To build all targets of the module the following command can be used:
+---
 
-```sh
-bazel build //score/...
-```
+## 📖 Documentation
 
-This command will instruct Bazel to build all targets that are under Bazel
-package `score/`. The ideal solution is to provide single target that builds
-artifacts, for example:
+Documentation lives in `docs/` and is built with `docs-as-code` (Sphinx). Build it locally with:
 
 ```sh
-bazel build //score/<module_name>:release_artifacts
+bazel build //:docs
 ```
 
-where `:release_artifacts` is filegroup target that collects all release
-artifacts of the module.
-
-> NOTE: This is just proposal, the final decision is on module maintainer how
-> the module code needs to be built.
-
-### 3️⃣ Run Tests
-
-```sh
-bazel test //tests/...
-```
+See the [module documentation](docs/index.rst) for the rendered content.
 
 ---
 
-## 🛠 Tools & Linters
-
-The template integrates **tools and linters** from **centralized repositories** to ensure consistency across projects.
+## ✅ Quality
 
-- **C++:** `clang-tidy`, `cppcheck`, `Google Test`
-- **Rust:** `clippy`, `rustfmt`, `Rust Unit Tests`
-- **CI/CD:** GitHub Actions for automated builds and tests
+See the [Quality](docs/index.rst) section of the module documentation for the existing tooling and the
+KPIs each one gates in CI (static analysis/linters, sanitizers, coverage, test tiers, traceability, license compliance).
 
 ---
 
-## 📖 Documentation
-
-- A **centralized docs structure** is planned.
-
----
-
-## ⚙️ `project_config.bzl`
-
-This file defines project-specific metadata used by Bazel macros, such as `dash_license_checker`.
-
-### 📌 Purpose
-
-It provides structured configuration that helps determine behavior such as:
-
-- Source language type (used to determine license check file format)
-- Safety level or other compliance info (e.g. ASIL level)
-
-### 📄 Example Content
-
-```python
-PROJECT_CONFIG = {
-    "asil_level": "QM",  # or "ASIL-A", "ASIL-B", etc.
-    "source_code": ["cpp", "rust"]  # Languages used in the module
-}
-```
-
-### 🔧 Use Case
-
-When used with macros like `dash_license_checker`, it allows dynamic selection of file types
- (e.g., `cargo`, `requirements`) based on the languages declared in `source_code`.
-
 ## IDE support
 
 ### Rust

docs/components/datarouter/detailed_design/logging_architecture.md

@@ -0,0 +1 @@
+../../../../score/datarouter/doc/design/logging_architecture.md

docs/components/datarouter/detailed_design/shm_apis.md

@@ -0,0 +1 @@
+../../../../score/datarouter/doc/design/shm_apis.md

docs/components/datarouter/index.rst

@@ -13,24 +13,24 @@
    # *******************************************************************************
 
 
-Data Router Documentation
+Datarouter
 =========================
 
-This section is reserved for data router-specific documentation.
-
-.. comp:: Data Router
-   :id: comp__data_router
+.. comp:: Datarouter
+   :id: comp__datarouter
    :security: YES
-   :safety: ASIL_B
+   :safety: QM
    :status: valid
    :implements: logic_arc_int__logging__logging
    :belongs_to: feat__logging
 
-   This is the datarouter component responsible for routing log messages to remote Diagnostics Log and Trace (DLT) backend.
+   Datarouter is the DLT (Diagnostic log and trace) daemon executable. It reads records from source shared-memory ring buffers, manages source
+   sessions, routes messages to configured channels via UDP multicast, and reports source statistics and message drops.
 
 .. toctree::
    :titlesonly:
    :maxdepth: 1
-   :glob:
 
-   *
+   requirements/index
+   detailed_design/logging_architecture
+   detailed_design/shm_apis

docs/components/datarouter/requirements.rst → docs/components/datarouter/requirements/index.rst

@@ -32,7 +32,7 @@ Datarouter Services
    :safety: QM
    :derived_from: feat_req__logging__compat_dlt, feat_req__logging__log_sinks_network
    :status: valid
-   :belongs_to: comp__data_router
+   :belongs_to: comp__datarouter
 
    Datarouter shall implement DLT server component. Datarouter provides the functionality to
    send messages using DLT protocol over UDP multicast transport.
@@ -44,7 +44,7 @@ Datarouter Services
    :safety: QM
    :derived_from: feat_req__logging__compat_dlt, feat_req__logging__config_log_filter, feat_req__logging__config_entity_id
    :status: valid
-   :belongs_to: comp__data_router
+   :belongs_to: comp__datarouter
 
    DLT server shall support multiple log channels as specified in AUTOSAR Diagnostic, Log and
    Trace Protocol Specification. The following parameters shall be configurable statically via
@@ -60,7 +60,7 @@ Datarouter Services
    :safety: QM
    :derived_from: feat_req__logging__filtering_log_levels, feat_req__logging__filtering_entity_id, feat_req__logging__config_log_filter
    :status: valid
-   :belongs_to: comp__data_router
+   :belongs_to: comp__datarouter
 
    DLT server shall support filtering of messages within each channel. The filter shall be
    parametrized with application ID, context ID, log level threshold. Initial filter set shall
@@ -74,7 +74,7 @@ Datarouter Services
    :safety: QM
    :derived_from: feat_req__logging__compat_dlt
    :status: valid
-   :belongs_to: comp__data_router
+   :belongs_to: comp__datarouter
 
    DLT server shall provide support for verbose DLT messages. Messages sent from mw::log
    library shall be sent via DLT using verbose mode.
@@ -89,7 +89,7 @@ DLT Quotas
    :safety: QM
    :derived_from: feat_req__logging__config_buffer_size, feat_req__logging__resource_comm_channel
    :status: valid
-   :belongs_to: comp__data_router
+   :belongs_to: comp__datarouter
 
    The component shall have the DLT bandwidth quota configuration in the file located at
    ``./etc/log-channels.json`` relative to the application specific location ``/opt/``.
@@ -101,7 +101,7 @@ DLT Quotas
    :safety: QM
    :derived_from: feat_req__logging__message_loss_handling, feat_req__logging__qos_message_handling
    :status: valid
-   :belongs_to: comp__data_router
+   :belongs_to: comp__datarouter
 
    It shall be possible to configure the action to drop DLT messages when a quota is exceeded.
 

docs/design_decisions/explicit_init.rst → docs/components/mw_log/design_decisions/explicit_init.rst

@@ -48,4 +48,4 @@ Explicit initialization of logging
 
    **Justification for the Decision**
 
-   Explicit logging initialization will simplify logging initialization in multi-language environments.
+   Explicit logging initialization will simplify logging initialization in multi-language environments.

docs/components/mw_log/detailed_design/datarouter_backend/README.md

@@ -0,0 +1 @@
+../../../../../score/mw/log/design/backend/datarouter_backend/README.md

docs/components/mw_log/detailed_design/file_output_backend.md

@@ -0,0 +1 @@
+../../../../score/mw/log/design/backend/file_output_backend.md

docs/components/mw_log/detailed_design/index.rst

@@ -0,0 +1,12 @@
+mw::log backend Detailed Design
+===============================
+
+The backend composition and recorder relationships are shown below:
+
+.. uml:: ../../../../score/mw/log/design/backend/mw_log_recorders.puml
+
+.. toctree::
+   :maxdepth: 1
+
+   file_output_backend
+   datarouter_backend/README

docs/components/mw/log/index.rst → docs/components/mw_log/index.rst

@@ -13,11 +13,9 @@
    # *******************************************************************************
 
 
-Logging Documentation
+mw::log
 =====================
 
-This section is reserved for middleware-specific documentation.
-
 .. comp:: Logging Component
    :id: comp__mw_logging
    :security: YES
@@ -26,11 +24,18 @@ This section is reserved for middleware-specific documentation.
    :implements: logic_arc_int__logging__logging
    :belongs_to: feat__logging
 
-   This is the logging component library responsible for selecting the appropriate log sinks based on configuration at runtime. It can perform tasks such as log formatting, filtering, and composite backend selection based on runtime context and configuration. The logging component is designed to be extensible, allowing for custom logging backend to be added as needed.
+   This is the logging middleware library responsible for providing conrete backends for the supported recorder
+   implementations. The logging component is designed to be extensible, allowing supported as well as custom logging
+   backend to be added as needed.
+
+   The ``mw::log`` implementation spans the ``score_baselibs`` (frontend) and ``score_logging`` (backend)
+   repositories; see the :doc:`feature architecture </features/architecture/index>` for the repository boundary
+   and cross-repository contract.
 
 .. toctree::
    :titlesonly:
    :maxdepth: 1
-   :glob:
 
-   *
+   requirements/index
+   detailed_design/index
+   design_decisions/explicit_init

docs/features/architecture/_assets/mw_log_repository_boundary.puml

@@ -0,0 +1,63 @@
+@startuml mw_log_architecture
+title mw::log (ASIL B): repository boundary
+
+skinparam componentStyle rectangle
+skinparam packageStyle rectangle
+skinparam linetype ortho
+
+package "score_baselibs" as Baselibs #LightYellow {
+  component "mw::log Frontend API\n(logger, log_stream, runtime)" as Frontend
+  component "Console Backend\n(static, built-in)" as Console
+  component "score_log Rust Facade\n(score_log, score_log_fmt,\nscore_log_fmt_macro)" as RustFacade
+  artifact "Frontend safety plan\n+ AoU forwarding (Usage Contract)" as FrontendPlan #line.dashed
+
+  Frontend -down-> Console : static composition (baseline)
+  Frontend .. FrontendPlan
+}
+
+package "score_logging" as Logging #LightBlue {
+  component "mw::log Concrete Recorders\n(file, remote/DLT, slog)" as Recorders
+  component "Backend Integration\ntargets (file, remote/datarouter, ...)" as Integration
+  component "Rust Log Bridge\n(score_log_bridge + adapter.cpp)" as RustBridge
+  component "Rust Bridge C++ Init API\n(score_log_bridge_cpp_init)" as RustCppInit
+  artifact "Backend safety plan\n+ AoU forwarding (Integration Contract)" as BackendPlan #line.dashed
+
+  Recorders -down-> Integration : static registration
+  Recorders .. BackendPlan
+}
+
+Recorders .up.> Frontend : implements Recorder interface\n(static registration via backend_table, baseline)
+
+RustBridge -up-> RustFacade : implements score_log\nlogger backend
+RustBridge -right-> Frontend : adapter.cpp calls\nRuntime::GetRecorder() (FFI)
+RustBridge .up.> Recorders : direct static link\n(score/issues/2848)
+RustCppInit -down-> RustBridge : set_default_logger (FFI)\nconfigures default logger
+
+package "Optional Future Evolution" as Future #WhiteSmoke {
+  component "Runtime Plugin Loading\n(dlopen-based)" as Runtime
+}
+
+Runtime .[#gray]right.> Frontend : experimental only
+
+note bottom of Future
+  Not an assumed production
+  commitment; decision-gated.
+end note
+
+note as N1
+  Each repo owns its own phase gates,
+  safety plan, and governance; the only
+  cross-repo contract is the Recorder
+  interface + static backend_table
+  registration (plugin_api.h is an
+  existing C ABI seam, not used
+  for static composition). The Rust
+  bridge reaches the Frontend/Recorders
+  the same way, via direct static
+  linkage rather than backend_table.
+end note
+
+Baselibs -[hidden]down-> N1
+Logging -[hidden]down-> N1
+
+@enduml