# autowarefoundation/autoware architecture

> Architecture diagram of the GitHub repository autowarefoundation/autoware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/autowarefoundation/autoware
- Repository: https://github.com/autowarefoundation/autoware

## Overview

This repository is a **meta-repository for Autoware**, not the autonomous-driving runtime itself. Its job is to assemble a full ROS-based workspace, provision developer machines and containers, and automate CI/release plumbing around the actual Autoware package repositories.

1. **Top-level role: workspace orchestrator**
   The root contains almost no application code. Instead, it coordinates how Autoware is built and used by pointing to external repositories through `.repos` manifests and by packaging environment/setup logic.

2. **Repository composition layer**
   The `repositories/` directory contains the main workspace manifests:
   - `autoware.repos`, `autoware-nightly.repos`
   - `simulator.repos`, `simulator-nightly.repos`
   - `tools.repos`, `tools-nightly.repos`
   - `extra-packages.repos`
   
   These files define which upstream repos get pulled into the ROS workspace. This is the primary dependency boundary for the project.

3. **Developer environment bootstrap**
   `setup-dev-env.sh`, `ansible/scripts/install-ansible.sh`, and the `.devcontainer/` definitions are the entry points for setting up a usable development host. They establish the local toolchain, then hand off to Ansible and/or container builds.

4. **Ansible as the provisioning engine**
   The `ansible/` tree is the main installation and configuration subsystem. It contains playbooks such as:
   - `install_dev_env.yaml`
   - `install_docker.yaml`
   - `install_nvidia.yaml`
   - `install_rmw.yaml`
   - `universe.yaml`
   - `openadkit.yaml`
   - `telegraf.yaml`
   
   These playbooks are the boundary between “host setup” and “Autoware workspace setup.”

5. **Ansible roles are modular system capabilities**
   Roles under `ansible/roles/` represent reusable infrastructure components rather than application features. Important groups include:
   - ROS2/runtime setup: `ros2`, `rmw_implementation`, `ros2_dev_tools`
   - GPU/graphics support: `cuda`, `nvidia_container_toolkit`, `kisak_mesa`, `qt5ct_setup`
   - build/dev tooling: `build_tools`, `dev_tools`, `docker_engine`
   - package/runtime helpers: `gdown`, `geographiclib`, `spconv`, `tensorrt`, `acados`, `agnocast`
   - observability: `telegraf`
   
   Each role encapsulates installation and configuration for one subsystem.

6. **Container image layer**
   The `docker/` directory defines the container-based development and execution environment:
   - base images: `base.Dockerfile`, `base-cuda.Dockerfile`
   - Autoware-specific images: `core.Dockerfile`, `universe.Dockerfile`, `universe-cuda.Dockerfile`
   - orchestration/build metadata: `docker-bake.hcl`
   - runtime entrypoint: `docker-entrypoint.sh`
   
   This is the main runtime packaging boundary for users who develop or run Autoware inside containers.

7. **Containerized examples and demos**
   `docker/examples/` provides ready-made compose configurations for common scenarios:
   - basic CPU/DRI/NVIDIA development
   - demo stacks such as `awsim` and `planning-simulator`
   
   These examples illustrate how the built images connect to ROS nodes, graphics devices, and simulator services.

8. **Devcontainer support**
   `.devcontainer/` contains multiple VS Code devcontainer variants, including `core-devel`, `universe-devel`, and `universe-devel-cuda`. These are thin wrappers over the Docker environment optimized for editor-based development.

9. **CI, release, and repo maintenance**
   `.github/workflows/` is extensive and focuses on repository hygiene and infrastructure automation:
   - Docker build/push, manifests, and build pipelines
   - health checks and pre-commit validation
   - release/backport/version-bump automation
   - spell checking, DCO, semantic PR checks, cache cleanup
   
   These workflows enforce consistency across the meta-repo and publish container artifacts.

10. **Automation for external sync and packaging**
    The repo also contains tooling for syncing files, dependency updates, and action reuse:
    - reusable workflows under `.github/actions/`
    - `ansible-galaxy-requirements.yaml`
    - `webauto-ci/` for scripted CI jobs
    - `repositories/*.repos` for pinned source sets
   
    This layer keeps the meta-repo aligned with upstream Autoware component repositories.

11. **Documentation and governance as support infrastructure**
    Files like `README.md`, `ansible/README.md`, `docker/README.md`, and the various GitHub templates/code-of-conduct files are not runtime components, but they are part of the operational boundary: they define how the workspace is consumed, maintained, and contributed to.

12. **What is not here**
    The `src/` directory is effectively empty in this repo. The actual autonomous-driving nodes, algorithms, and launch graphs live in the repositories referenced by the `.repos` files, especially Autoware Core/Universe and related launch/config repos.

Overall architecture: **this repo assembles source, environment, and packaging around Autoware**. The main flow is:
repository manifests → workspace checkout → Ansible/container provisioning → developer/runtime environment → CI/release automation.

Main entry points: [`ansible/playbooks`](https://github.com/autowarefoundation/autoware/tree/main/ansible/playbooks) (Playbooks), [`repositories`](https://github.com/autowarefoundation/autoware/tree/main/repositories) (Repo sets), [`docker`](https://github.com/autowarefoundation/autoware/tree/main/docker) (Docker images), [`.github`](https://github.com/autowarefoundation/autoware/blob/main/.github) (GitHub automation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_manifests["Workspace manifests"]
  node_manifests["Repo sets<br/>workspace manifests"]
  node_autoware_repos["Autoware set<br/>source manifest<br/>[autoware.repos]"]
  node_autoware_nightly_repos["Nightly core<br/>source manifest"]
  node_simulator_repos["Simulator set<br/>source manifest<br/>[simulator.repos]"]
  node_tools_repos["Tools set<br/>source manifest<br/>[tools.repos]"]
end

subgraph group_grp_provision["Provisioning"]
  node_dev_setup["Dev bootstrap<br/>shell bootstrap<br/>[setup-dev-env.sh]"]
  node_install_ansible["Ansible install<br/>bootstrap script<br/>[install-ansible.sh]"]
  node_ansible_playbooks["Playbooks<br/>provisioning plans"]
  node_ansible_roles["Roles<br/>reusable capabilities"]
  node_ros2_role["ROS2 stack<br/>ansible role"]
  node_gpu_roles["GPU support<br/>ansible roles"]
  node_runtime_roles["Runtime libs<br/>ansible roles"]
end

subgraph group_grp_container["Container runtime"]
  node_docker_layer["Docker images<br/>container images"]
  node_docker_examples["Compose demos<br/>compose examples"]
  node_devcontainers["Devcontainers<br/>editor containers<br/>[.devcontainer]"]
end

subgraph group_grp_automation["Automation"]
  node_github_automation["GitHub automation<br/>ci and governance<br/>[.github]"]
  node_webauto_ci["Webauto CI<br/>scripted ci<br/>[.webauto-ci]"]
end

node_root["Autoware meta<br/>meta-repo orchestrator"]
node_support_docs["Support docs<br/>docs and policy<br/>[README.md]"]
node_src_empty["Empty src<br/>workspace placeholder"]

node_root -->|"pins"| node_manifests
node_root -->|"boots"| node_dev_setup
node_root -->|"provisions"| node_ansible_playbooks
node_root -->|"packages"| node_docker_layer
node_root -->|"governs"| node_github_automation
node_manifests -->|"includes"| node_autoware_repos
node_manifests -->|"includes"| node_autoware_nightly_repos
node_manifests -->|"includes"| node_simulator_repos
node_manifests -->|"includes"| node_tools_repos
node_dev_setup -->|"uses"| node_install_ansible
node_install_ansible -->|"enables"| node_ansible_playbooks
node_ansible_playbooks -->|"orchestrates"| node_ansible_roles
node_ansible_playbooks -.->|"prepares"| node_docker_layer
node_ansible_playbooks -->|"invokes"| node_ros2_role
node_ansible_playbooks -->|"invokes"| node_gpu_roles
node_ansible_playbooks -->|"invokes"| node_runtime_roles
node_docker_layer -->|"demonstrates"| node_docker_examples
node_docker_layer -->|"wraps"| node_devcontainers
node_github_automation -->|"drives"| node_webauto_ci
node_github_automation -.->|"documents"| node_support_docs
node_manifests -.->|"populates"| node_src_empty
node_support_docs -.->|"explains"| node_root

click node_manifests "https://github.com/autowarefoundation/autoware/tree/main/repositories"
click node_autoware_repos "https://github.com/autowarefoundation/autoware/blob/main/repositories/autoware.repos"
click node_autoware_nightly_repos "https://github.com/autowarefoundation/autoware/blob/main/repositories/autoware-nightly.repos"
click node_simulator_repos "https://github.com/autowarefoundation/autoware/blob/main/repositories/simulator.repos"
click node_tools_repos "https://github.com/autowarefoundation/autoware/blob/main/repositories/tools.repos"
click node_dev_setup "https://github.com/autowarefoundation/autoware/blob/main/setup-dev-env.sh"
click node_install_ansible "https://github.com/autowarefoundation/autoware/blob/main/ansible/scripts/install-ansible.sh"
click node_ansible_playbooks "https://github.com/autowarefoundation/autoware/tree/main/ansible/playbooks"
click node_ansible_roles "https://github.com/autowarefoundation/autoware/tree/main/ansible/roles"
click node_ros2_role "https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2"
click node_gpu_roles "https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/cuda"
click node_runtime_roles "https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rmw_implementation"
click node_docker_layer "https://github.com/autowarefoundation/autoware/tree/main/docker"
click node_docker_examples "https://github.com/autowarefoundation/autoware/tree/main/docker/examples"
click node_devcontainers "https://github.com/autowarefoundation/autoware/blob/main/.devcontainer"
click node_github_automation "https://github.com/autowarefoundation/autoware/blob/main/.github"
click node_webauto_ci "https://github.com/autowarefoundation/autoware/blob/main/.webauto-ci"
click node_support_docs "https://github.com/autowarefoundation/autoware/blob/main/README.md"
click node_src_empty "https://github.com/autowarefoundation/autoware/tree/main/src"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manifests,node_autoware_repos,node_autoware_nightly_repos,node_simulator_repos,node_tools_repos toneBlue
class node_dev_setup,node_install_ansible,node_ansible_playbooks,node_ansible_roles,node_ros2_role,node_gpu_roles,node_runtime_roles toneAmber
class node_docker_layer,node_docker_examples,node_devcontainers toneMint
class node_github_automation,node_webauto_ci toneRose
class node_root,node_support_docs,node_src_empty toneNeutral
```

## Components

### Workspace manifests

Pinned source-set manifests that define which upstream repositories are checked out into the workspace.

- [Repo sets](https://github.com/autowarefoundation/autoware/tree/main/repositories): workspace manifests · `.repos` files that pin the upstream Autoware, simulator, tools, and extra package source sets. · `repositories`
- [Autoware set](https://github.com/autowarefoundation/autoware/blob/main/repositories/autoware.repos): source manifest · Primary Autoware workspace composition for the core stack. · `repositories/autoware.repos`
- [Nightly core](https://github.com/autowarefoundation/autoware/blob/main/repositories/autoware-nightly.repos): source manifest · Nightly variant of the core Autoware workspace set. · `repositories/autoware-nightly.repos`
- [Simulator set](https://github.com/autowarefoundation/autoware/blob/main/repositories/simulator.repos): source manifest · Workspace composition for simulator-related repositories. · `repositories/simulator.repos`
- [Tools set](https://github.com/autowarefoundation/autoware/blob/main/repositories/tools.repos): source manifest · Workspace composition for tooling and auxiliary repositories. · `repositories/tools.repos`

### Provisioning

Host and workspace setup via shell bootstrap and Ansible playbooks/roles.

- [Dev bootstrap](https://github.com/autowarefoundation/autoware/blob/main/setup-dev-env.sh): shell bootstrap · Entry scripts that start local machine setup before Ansible/container provisioning takes over. · `setup-dev-env.sh`
- [Ansible install](https://github.com/autowarefoundation/autoware/blob/main/ansible/scripts/install-ansible.sh): bootstrap script · Installs or prepares Ansible on the host so provisioning can run. · `ansible/scripts/install-ansible.sh`
- [Playbooks](https://github.com/autowarefoundation/autoware/tree/main/ansible/playbooks): provisioning plans · Host and workspace setup entrypoints such as dev env, Docker, NVIDIA, RMW, and universe installs. · `ansible/playbooks`
- [Roles](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles): reusable capabilities · Modular infrastructure capabilities for ROS2, GPU support, build tools, observability, and package helpers. · `ansible/roles`
- [ROS2 stack](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2): ansible role · ROS2 and developer toolchain setup for the workspace. · `ansible/roles/ros2`
- [GPU support](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/cuda): ansible roles · NVIDIA, CUDA, Mesa, and Qt/graphics setup for accelerated development and visualization. · `ansible/roles/cuda`
- [Runtime libs](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rmw_implementation): ansible roles · Workspace runtime helpers such as RMW, GeographicLib, Spconv, TensorRT, acados, and Agnocast. · `ansible/roles/rmw_implementation`

### Container runtime

Docker images, compose examples, and devcontainer wrappers for containerized development and execution.

- [Docker images](https://github.com/autowarefoundation/autoware/tree/main/docker): container images · Base and Autoware-specific Dockerfiles plus build metadata and entrypoint for containerized use. · `docker`
- [Compose demos](https://github.com/autowarefoundation/autoware/tree/main/docker/examples): compose examples · Ready-made compose stacks for CPU, DRI, NVIDIA, and demo scenarios like AWSIM and planning simulator. · `docker/examples`
- [Devcontainers](https://github.com/autowarefoundation/autoware/blob/main/.devcontainer): editor containers · VS Code devcontainer variants layered over the Docker environment for editor-based development. · `.devcontainer`

### Automation

CI, release, maintenance, and reusable workflow plumbing around the meta-repository.

- [GitHub automation](https://github.com/autowarefoundation/autoware/blob/main/.github): ci and governance · Workflows, reusable actions, templates, and repo-maintenance automation for the meta-repo. · `.github`
- [Webauto CI](https://github.com/autowarefoundation/autoware/blob/main/.webauto-ci): scripted ci · Standalone scripted CI jobs for setup and build workflows. · `.webauto-ci`

### Other components

- **Autoware meta**: meta-repo orchestrator · Top-level repository that assembles the Autoware workspace, environment, and automation around external package repositories.
- [Support docs](https://github.com/autowarefoundation/autoware/blob/main/README.md): docs and policy · Repository-level documentation, contribution guidance, and governance files that define usage and maintenance boundaries. · `README.md`
- [Empty src](https://github.com/autowarefoundation/autoware/tree/main/src): workspace placeholder · Workspace source directory placeholder; the real runtime nodes live in external repositories referenced by the manifests. · `src`

## Connections

- Autoware meta → Repo sets: pins · Defines the workspace source sets to fetch.
- Autoware meta → Dev bootstrap: boots · Starts local developer-machine setup.
- Autoware meta → Playbooks: provisions · Delegates host and environment setup to Ansible playbooks.
- Autoware meta → Docker images: packages · Builds runnable development/runtime images.
- Autoware meta → GitHub automation: governs · Automates CI, release, and repo hygiene.
- Repo sets → Autoware set: includes · Primary Autoware source set.
- Repo sets → Nightly core: includes · Nightly core source set.
- Repo sets → Simulator set: includes · Simulator source set.
- Repo sets → Tools set: includes · Tooling source set.
- Dev bootstrap → Ansible install: uses · Bootstraps Ansible-based provisioning.
- Ansible install → Playbooks: enables · Provides the installer for the main provisioning engine.
- Playbooks → Roles: orchestrates · Compose reusable system capabilities into host/workspace setup.
- Playbooks → Docker images: prepares · Can install and configure the Docker runtime environment.
- Playbooks → ROS2 stack: invokes · Sets up ROS2 runtime and tooling.
- Playbooks → GPU support: invokes · Configures CUDA/NVIDIA/graphics support.
- Playbooks → Runtime libs: invokes · Installs key runtime libraries and helpers.
- Docker images → Compose demos: demonstrates · Example compose stacks show how images are assembled into scenarios.
- Docker images → Devcontainers: wraps · Devcontainer variants build on the Docker images.
- GitHub automation → Webauto CI: drives · Reusable workflows and CI jobs coordinate repo automation.
- GitHub automation → Support docs: documents · Templates and contribution guidance shape repo governance.
- Repo sets → Empty src: populates · Workspace checkout fills the source tree from external repositories.
- Support docs → Autoware meta: explains · Documentation describes how the meta-repository is used and maintained.
