# intel/ad-rss-lib architecture

> Architecture diagram of the GitHub repository intel/ad-rss-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/intel/ad-rss-lib
- Repository: https://github.com/intel/ad-rss-lib

## Overview

##### Project Type & Overall Purpose
- This is a C++ library for implementing Responsibility Sensitive Safety (RSS) for automated vehicles. Its purpose is to take processed sensor input (an object list) and produce a range of safety responses (acceleration restrictions) for use in automated driving systems.
- In addition, there are Python bindings to enable integration with Python-based systems and an “ad_rss_map_integration” module that demonstrates how to integrate the core RSS functionality with map data (used for providing road boundary and map information).

##### Main Components
a. Core RSS Library (ad_rss)
– Submodules:
- Core: Implements the safety checks – including RssCheck, RssResponseResolving, and RssSituationExtraction.
- Situation: Contains the RSS formulas and physics calculations (see files like RssFormulas, Physics.cpp/hpp).
- State: Implements the state evaluation aspects (e.g., lateral and longitudinal responses, RssStateEvaluator, etc.) found in the ‘state’ directory.
- World/Unstructured: Contains modules that handle additional aspects (e.g., lane driving, object topology, world modeling, geometry).
– Generated code:
- The project creates generated header and source files for many of these components (for example, in the “generated/include” and “generated/src” directories) to ensure consistency between different parts of the RSS functionality.

b. Python Binding Module
– Under the “python” directories (in both the ad_rss and ad_rss_map_integration folders), this provides an interface to use the library with Python.
– Key components such as “AdRssPythonModule.cpp.in”, “generate_python_lib.py.in”, and “setup.py.in” should be highlighted as integration points.

c. Integration Module (ad_rss_map_integration)
– This module demonstrates how to integrate the RSS library with automated driving map data.
– Important components include classes for logging, converting objects, and creating RSS scenes (files like RssSceneCreator, RssSceneCreation, and related test resources).

d. Build, Testing, and Documentation Infrastructure
– Build System: Emphasize the cmake support, including CMakeLists.txt files in multiple directories and cmake configuration modules.
– Continuous Integration: Include the GitHub workflows (under “.github/workflows”) that handle building, testing, code formatting, static analysis, and documentation deployment.
– Testing Components: There are extensive unit tests (in “tests”). The test directories for core, situation, state, world, and integration are part of ensuring the robustness of the implementation.
– Documentation: The “doc” directories contain markdown, Doxygen configurations (including doxyfiles), and images to support the architectural overview. This helps users understand safe driving scenarios and design decisions.

##### Relationships and Interactions
- Within the core RSS library, the input object list is processed to form “situations” (for each pair of ego vehicle and external object). These situations are then analyzed by:
- Core Processing (RssSituationChecking, RssResponseResolving, etc.)
- Physics and formula evaluations (RssFormulas and Physics)
- State evaluation that results in the proper acceleration restrictions.
- The map integration module uses the core RSS functionality and wraps it to account for additional map information (like road boundaries) and to generate more contextualized RSS scenes.
- Python bindings provide a gateway for interfacing between the C++ core functionality and Python-driven applications.
- Testing and CI pipelines are connected to all the major modules to ensure quality and compliance.

##### Architectural Patterns & Key Design Principles
- Modular Design: The library is split into clearly defined modules (core, situation, state, world, unstructured, integration) which fosters reusability and testability.
- Separation of Concerns: Input conversion and actuation conversion are deliberately outside the library scope, focusing solely on calculating the safety response.
- Automated Building & Testing: Use of cmake, GitHub workflows, and structured test directories enforce continuous integration practices.
- Use of Code Generation: The “generated” code directories highlight that parts of the API are auto-generated to enforce consistency and proper input range checking.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    E1["Sensor Data (external)"]:::external
    E2["Input Conversion (external)"]:::external
    E1 -->|"convertsTo"| E2
    E2 -->|"feeds"| CP_Core

    %% Core RSS Library Subgraph
    subgraph "Core RSS Library"
        CP_Core["Core Processing"]:::core
        SP["Situation & Physics"]:::core
        SE["State Evaluation"]:::core
        WU["World & Unstructured"]:::core
        SR["Safety Response (Acceleration Restrictions)"]:::core
        CP_Core -->|"processes"| SP
        SP -->|"evaluates"| SE
        WU -->|"provides context"| SE
        SE -->|"resultsIn"| SR
    end

    %% Integration Layers
    PB["Python Binding Module"]:::integration
    MI["Map Integration Module"]:::integration
    SR -->|"exposesAPI"| PB
    SR -->|"integratesWith"| MI

    %% Supporting Infrastructure Subgraph
    subgraph "Supporting Infrastructure"
        BS["Build System"]:::support
        CI["CI/CD Pipelines"]:::support
        TEST["Testing"]:::support
        DOC["Documentation"]:::support
    end
    SR -->|"builtWith"| BS
    SR -->|"verifiedBy"| CI
    SR -->|"testedBy"| TEST
    SR -->|"explainedIn"| DOC
    PB -->|"usesInfra"| BS
    MI -->|"usesInfra"| BS

    %% Class Definitions
    classDef external fill:#ddf,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef integration fill:#bfb,stroke:#333,stroke-width:2px;
    classDef support fill:#fdc,stroke:#333,stroke-width:2px;

    %% Click Events for Core RSS Library Components
    click CP_Core "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/include/ad/rss/core"
    click CP_Core "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/src/core"
    click SP "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/include/ad/rss/situation"
    click SP "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/src/situation"
    click SE "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/generated/include/ad/rss/state"
    click SE "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/generated/src/ad/rss/state"
    click SE "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/include/ad/rss/state"
    click WU "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/include/ad/rss/unstructured"
    click WU "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/src/unstructured"
    click WU "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/generated/include/ad/rss/world"
    click WU "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/src/world"

    %% Click Events for Integration Modules
    click PB "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/python"
    click MI "https://github.com/intel/ad-rss-lib/tree/main/ad_rss_map_integration/include/ad/rss/map"
    click MI "https://github.com/intel/ad-rss-lib/tree/main/ad_rss_map_integration/src"
    click MI "https://github.com/intel/ad-rss-lib/tree/main/ad_rss_map_integration/python"

    %% Click Events for Supporting Infrastructure
    click BS "https://github.com/intel/ad-rss-lib/blob/main/ad_rss/CMakeLists.txt"
    click BS "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/cmake"
    click BS "https://github.com/intel/ad-rss-lib/blob/main/ad_rss_map_integration/CMakeLists.txt"
    click BS "https://github.com/intel/ad-rss-lib/tree/main/cmake/"
    click CI "https://github.com/intel/ad-rss-lib/tree/main/.github/workflows"
    click TEST "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/tests"
    click TEST "https://github.com/intel/ad-rss-lib/tree/main/ad_rss_map_integration/tests"
    click DOC "https://github.com/intel/ad-rss-lib/tree/main/ad_rss/doc"
    click DOC "https://github.com/intel/ad-rss-lib/tree/main/ad_rss_map_integration/doc"
    click DOC "https://github.com/intel/ad-rss-lib/tree/main/doc/"
```
