# tier4/caret architecture

> Architecture diagram of the GitHub repository tier4/caret, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tier4/caret
- Repository: https://github.com/tier4/caret

## Overview

##### Project Type & Purpose
- CARET is a performance evaluation tool designed for evaluating and tracing ROS 2 application behavior. It sits at the intersection of instrumentation (via function hooks and injected tracepoints) and data analysis/visualization.
- The overall ecosystem is multi-repository – with separate components for defining the tracepoints (caret_trace), analyzing data (caret_analyze and its C++ implementation), command-line utilities (ros2caret), and documentation/support – but the provided file tree represents the meta repository that ties these elements together via .repos files, Ansible playbooks, docker files, and release scripts.

##### Major Architectural Components (to include
a. CORE COMPONENTS:
- Instrumentation / Tracepoint Injection:
- Represented by repositories like caret_trace and the forked rclcpp and ros2_tracing.
- The system deploys function hooks that add additional tracepoints for improved resolution.
- Data Analysis and Visualization:
- Handled by caret_analyze (and its C++ helper implementation) which processes trace data and provides analytics.
- Command Line Interface:
- The CLI layer (ros2caret) offers commands for initiating and interacting with the evaluation.
b. INFRASTRUCTURE / DEPLOYMENT:
- Ansible-based Deployment and Configuration:
- The “ansible” directory with its various roles (caret, caret_iron, caret_jazzy, cyclonedds, etc.) is used for configuring different deployment setups.
- That these roles manage installation and environment-specific configuration (e.g., different “playbook.yml” scripts for Autoware integrations).
- Docker Containerization:
- The “docker” folder (with Dockerfile variants like build_autoware.dockerfile) is used for containerized builds and deployments.
- Release Automation:
- The “release_script” folder contains scripts to package CARET (e.g., release_caret.sh) ensuring versioned and repeatable builds.
c. CI/CD and Quality Checks:
- GitHub Actions Workflows:
- Located under .github/workflows, these automate building, testing (including integration with Autoware), pre-commit checks, and dependency sync.
- Configuration files like .pre-commit-config.yaml that enforce code quality standards.
- Additional tools such as ansible-lint, yamllint, prettier, etc., act as quality and style enforcers.

##### Relationships and Data Flow
- How a ROS 2 application would run on nodes with CARET tracepoints injected. Data from these nodes is then collected (or streamed) to an analysis engine.
- The CLI component lets users interact with both the trace and analysis parts.
- Deployment and configuration tools (Ansible and Docker) manage the installation and runtime environment for the entire system.
- CI/CD pipelines provide continuous integration and validation, ensuring that changes to tracepoints, analysis modules, and deployment scripts are tested.

##### Architectural Patterns & Design Principles
- Modularity: The multi-repository approach is designed so that each core functionality is encapsulated (evaluation, data analysis, command interface, etc.).
- Separation of Concerns: Instrumentation, analysis, deployment, and documentation are separated into different components and roles.
- Extensibility: The use of multiple .repos files (caret.repos, caret_iron.repos, etc.) and distinct Ansible roles hints at supporting different configurations/environments (e.g., different distributions or integrations like Autoware).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interaction/Interface Layer
    subgraph "Interaction/Interface Layer"
        CLI["Command Line Interface: ros2caret"]:::interface
        Documentation["Documentation & Support"]:::interface
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        Instrumentation["Instrumentation: ROS 2 with CARET Tracepoints"]:::core
        Analysis["Data Analysis Engine (caret_analyze & C++ helper)"]:::core
    end

    %% Deployment/Configuration Layer
    subgraph "Deployment/Configuration Layer"
        %% Ansible Deployment Subgraph
        subgraph "Ansible Deployment"
            CaretRole["Role: CARET"]:::deployment
            CaretIronRole["Role: CARET_Iron"]:::deployment
            CaretJazzyRole["Role: CARET_Jazzy"]:::deployment
            CycloneddsRole["Role: Cyclone_DDS"]:::deployment
            LTTngRole["Role: LTTng"]:::deployment
            RosTracingRole["Role: ROS-Tracing"]:::deployment
            VisualizerRole["Role: Visualizer"]:::deployment
            Playbook["Playbook: ansible/playbook.yml"]:::deployment
            PlaybookIron["Playbook_Iron: ansible/playbook_iron.yml"]:::deployment
            PlaybookJazzy["Playbook_Jazzy: ansible/playbook_jazzy.yml"]:::deployment
        end

        %% Docker Containerization Node
        Docker["Docker Containerization"]:::deployment

        %% Release Automation Subgraph
        subgraph "Release Automation"
            ReleaseScript["Script: release_caret.sh"]:::deployment
            TemplateRepos["Template: template_caret.repos"]:::deployment
        end

        %% CI/CD & Quality Subgraph
        subgraph "CI/CD & Quality"
            GithubActions["GitHub_Actions_Workflows"]:::cicd
            PreCommit["Pre-commit_Config"]:::cicd
            PreCommitOptional["Pre-commit_Optional_Config"]:::cicd
            AnsibleLint["Ansible_Lint_Config"]:::cicd
            YAMLLint["YAML_Lint_Config"]:::cicd
            Prettier["Prettier_Config"]:::cicd
        end
    end

    %% Connections: Interaction/Interface to Core Processing
    CLI -->|"triggers"| Instrumentation
    CLI -->|"queries"| Analysis
    Documentation -->|"guides"| CLI
    Documentation -->|"documents"| Analysis

    %% Connections: Core Processing Data Flow
    Instrumentation -->|"trace_data"| Analysis

    %% Connections: Deployment/Configuration to Core Processing (using representative nodes)
    CaretRole -->|"deploys"| Instrumentation
    CaretRole -->|"configures"| Analysis
    Docker -->|"hosts"| Instrumentation
    Docker -->|"hosts"| Analysis
    ReleaseScript -->|"packages"| Instrumentation
    ReleaseScript -->|"packages"| Analysis

    %% Connections: CI/CD impacting Deployment
    GithubActions -->|"validates"| CaretRole
    GithubActions -->|"triggers"| ReleaseScript

    %% Styles
    classDef interface fill:#fc9,stroke:#333,stroke-width:2px;
    classDef core fill:#cfc,stroke:#333,stroke-width:2px;
    classDef deployment fill:#ccf,stroke:#333,stroke-width:2px;
    classDef cicd fill:#f9c,stroke:#333,stroke-width:2px;

    %% Click Events for Ansible Roles and Playbooks
    click CaretRole "https://github.com/tier4/caret/tree/main/ansible/roles/caret"
    click CaretIronRole "https://github.com/tier4/caret/tree/main/ansible/roles/caret_iron"
    click CaretJazzyRole "https://github.com/tier4/caret/tree/main/ansible/roles/caret_jazzy"
    click CycloneddsRole "https://github.com/tier4/caret/tree/main/ansible/roles/cyclonedds"
    click LTTngRole "https://github.com/tier4/caret/tree/main/ansible/roles/lttng"
    click RosTracingRole "https://github.com/tier4/caret/tree/main/ansible/roles/ros-tracing"
    click VisualizerRole "https://github.com/tier4/caret/tree/main/ansible/roles/visualizer"
    click Playbook "https://github.com/tier4/caret/blob/main/ansible/playbook.yml"
    click PlaybookIron "https://github.com/tier4/caret/blob/main/ansible/playbook_iron.yml"
    click PlaybookJazzy "https://github.com/tier4/caret/blob/main/ansible/playbook_jazzy.yml"

    %% Click Event for Docker
    click Docker "https://github.com/tier4/caret/blob/main/docker/build_autoware.dockerfile"

    %% Click Events for Release Automation
    click ReleaseScript "https://github.com/tier4/caret/blob/main/release_script/release_caret.sh"
    click TemplateRepos "https://github.com/tier4/caret/blob/main/release_script/template_caret.repos"

    %% Click Events for CI/CD & Quality
    click GithubActions "https://github.com/tier4/caret/tree/main/.github/workflows/"
    click PreCommit "https://github.com/tier4/caret/blob/main/.pre-commit-config.yaml"
    click PreCommitOptional "https://github.com/tier4/caret/blob/main/.pre-commit-config-optional.yaml"
    click AnsibleLint "https://github.com/tier4/caret/blob/main/.ansible-lint"
    click YAMLLint "https://github.com/tier4/caret/blob/main/.yamllint.yaml"
    click Prettier "https://github.com/tier4/caret/blob/main/.prettierrc.yaml"
```
