# agorarobotics/navigation2 architecture

> Architecture diagram of the GitHub repository agorarobotics/navigation2, 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/agorarobotics/navigation2
- Repository: https://github.com/agorarobotics/navigation2

## Overview

This project is the ROS2 Navigation2 (Nav2) stack – a full‐featured, modular mobile robot navigation system. It is quite large and component-driven, with many interdependent modules that include localization (e.g. nav2_amcl), behavior trees (nav2_behavior_tree, nav2_bt_navigator), planners (nav2_navfn_planner, nav2_planner, nav2_smac_planner, nav2_theta_star_planner), controllers (nav2_controller, nav2_dwb_controller, nav2_regulated_pure_pursuit_controller, etc.), costmaps (nav2_costmap_2d), lifecycle management (nav2_lifecycle_manager), map servers, and various utilities and plugins.

##### Main architectural layers and components
- Frontend / User Interaction: Components like the simple commander, RViz plugins (nav2_rviz_plugins), and launch files, which are used to start the system and provide visualization.
- Core Navigation Pipeline: This includes modules for localization (e.g. nav2_amcl), mapping and costmap computation (nav2_costmap_2d, nav2_voxel_grid), global and local planners (nav2_navfn_planner, nav2_planner, nav2_smac_planner, nav2_theta_star_planner), and trajectory execution (nav2_controller, nav2_dwb_controller, nav2_regulated_pure_pursuit_controller, nav2_graceful_controller).
- Behavior Management: Behavior Tree components (nav2_behavior_tree, nav2_bt_navigator) that manage high-level decision-making and recovery behaviors.
- Lifecycle Management: Managed by nav2_lifecycle_manager and underlying lifecycle utilities (nav2_util) that oversee node state transitions.
- System Integration & Plugins: Various plugins (found across many modules) that allow extension points for planners, controllers, costmap filters, and plugins for docking (nav2_docking) and other specialized tasks.
- Middleware & Message Definitions: Packages like nav2_msgs, nav2_core, and the utility libraries that define interfaces and help with node-to-node communication.

- Directional data flows and command flows between the frontend (UI or launch files) and core modules.
- How the lifecycle manager acts as the orchestrator that brings up and shuts down the nodes across the system.
- For the navigation pipeline, indicate that sensor data and map input flow into costmap modules, then feed into the planner and controller modules.
- Dependency on ROS2 middleware: the processes are implemented as ROS nodes communicating via topics, services, and actions.

##### Design patterns and architectural principles
- Layered architecture: The stack typically follows a pipeline – sensor input, perception, planning, execution, and then feedback loops, each implemented as separate modules.
- Separation of concerns: For instance, there is a separation between the planning (global and local) and costmap generation.

##### Technologies and frameworks
- ROS2 as the underlying middleware.
- CMake and package management (the file tree shows many CMakeLists.txt files) to illustrate build and integration.
- The reliance on behavior trees (BTs) with the nav2_behavior_tree engine.
- Integration with CI/CD (CircleCI, GitHub Actions, etc.) can be shown as an external process that supports the system.
- Standard messaging definitions via nav2_msgs.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface / Launch / Visualization Layer
    subgraph "User Interface / Launch / Visualization"
        UI1["Simple Commander (Launch)"]:::frontend
        UI2["Simple Commander (Core)"]:::frontend
        UI3["RViz Plugins (Include)"]:::frontend
        UI4["RViz Plugins (Src)"]:::frontend
        UI5["Navigation Launch (nav2_bringup)"]:::frontend
    end

    %% Navigation Pipeline Layer
    subgraph "Navigation Pipeline"
        subgraph "Localization & Mapping"
            NM1["Localization (nav2_amcl)"]:::pipeline
            NM2["Costmap 2D (nav2_costmap_2d)"]:::pipeline
            NM3["Voxel Grid (nav2_voxel_grid)"]:::pipeline
        end
        subgraph "Planning"
            NP1["Navfn Planner (nav2_navfn_planner)"]:::pipeline
            NP2["Planner Server (nav2_planner)"]:::pipeline
            NP3["Smac Planner (nav2_smac_planner)"]:::pipeline
            NP4["Theta Star Planner (nav2_theta_star_planner)"]:::pipeline
        end
        subgraph "Execution"
            NE1["Controller Server (nav2_controller)"]:::pipeline
            NE2["DWB Controller (nav2_dwb_controller)"]:::pipeline
            NE3["Regulated Pure Pursuit (nav2_regulated_pure_pursuit_controller)"]:::pipeline
            NE4["Graceful Controller (nav2_graceful_controller)"]:::pipeline
        end
    end

    %% Behavior / Recovery Layer
    subgraph "Behavior / Recovery"
        B1["Behavior Tree Engine (nav2_behavior_tree)"]:::behavior
        B2["BT Navigator (nav2_bt_navigator)"]:::behavior
        B3["Behaviors (nav2_behaviors)"]:::behavior
    end

    %% Infrastructure & Middleware Layer
    subgraph "Infrastructure & Middleware"
        I1["Lifecycle Manager (nav2_lifecycle_manager)"]:::infra
        I2["Lifecycle Utilities (nav2_util)"]:::infra
        I3["Docking Plugins (nav2_docking)"]:::plugin
        I4["Message Definitions (nav2_msgs)"]:::infra
        I5["Core Interfaces (nav2_core)"]:::infra
    end

    %% Relationships between Layers and Components
    %% UI to Navigation Pipeline
    UI5 -->|"commands"| NM2
    UI1 -->|"commands"| NM2
    UI2 -->|"commands"| NM2
    UI3 -->|"visualize"| UI5
    UI4 -->|"visualize"| UI5

    %% Within Navigation Pipeline
    NM1 -->|"data"| NM2
    NM2 -->|"mapInput"| NP1
    NM2 -->|"mapInput"| NP2
    NM2 -->|"mapInput"| NP3
    NM3 -->|"gridInput"| NP4

    NP1 -->|"plan"| NE1
    NP2 -->|"plan"| NE1
    NP3 -->|"plan"| NE2
    NP4 -->|"plan"| NE2

    NE1 -->|"execute"| B2
    NE2 -->|"execute"| B2
    NE3 -->|"execute"| B2
    NE4 -->|"execute"| B2

    %% Behavior feedback to Planning
    B2 -->|"feedback"| NP1
    B2 -->|"feedback"| NP3

    %% Lifecycle management across layers
    I1 -->|"lifecycle"| UI5
    I1 -->|"lifecycle"| NM1
    I1 -->|"lifecycle"| NP1
    I1 -->|"lifecycle"| B2

    %% Message and Interface Connections
    I4 ---|"msg"| NP2
    I5 ---|"interface"| NE1

    %% Plugin connections from Execution to System Integration
    NE1 -->|"plugins"| I3
    NE2 -->|"plugins"| I3

    %% Click Events for Frontend / User Interaction
    click UI1 "https://github.com/agorarobotics/navigation2/tree/main/nav2_simple_commander/launch"
    click UI2 "https://github.com/agorarobotics/navigation2/tree/main/nav2_simple_commander/nav2_simple_commander"
    click UI3 "https://github.com/agorarobotics/navigation2/tree/main/nav2_rviz_plugins/include/nav2_rviz_plugins"
    click UI4 "https://github.com/agorarobotics/navigation2/tree/main/nav2_rviz_plugins/src"
    click UI5 "https://github.com/agorarobotics/navigation2/tree/main/nav2_bringup/launch"

    %% Click Events for Core Navigation Pipeline
    click NM1 "https://github.com/agorarobotics/navigation2/tree/main/nav2_amcl"
    click NM2 "https://github.com/agorarobotics/navigation2/tree/main/nav2_costmap_2d"
    click NM3 "https://github.com/agorarobotics/navigation2/tree/main/nav2_voxel_grid"
    click NP1 "https://github.com/agorarobotics/navigation2/tree/main/nav2_navfn_planner"
    click NP2 "https://github.com/agorarobotics/navigation2/tree/main/nav2_planner"
    click NP3 "https://github.com/agorarobotics/navigation2/tree/main/nav2_smac_planner"
    click NP4 "https://github.com/agorarobotics/navigation2/tree/main/nav2_theta_star_planner"
    click NE1 "https://github.com/agorarobotics/navigation2/tree/main/nav2_controller"
    click NE2 "https://github.com/agorarobotics/navigation2/tree/main/nav2_dwb_controller"
    click NE3 "https://github.com/agorarobotics/navigation2/tree/main/nav2_regulated_pure_pursuit_controller"
    click NE4 "https://github.com/agorarobotics/navigation2/tree/main/nav2_graceful_controller"

    %% Click Events for Behavior / Recovery
    click B1 "https://github.com/agorarobotics/navigation2/tree/main/nav2_behavior_tree"
    click B2 "https://github.com/agorarobotics/navigation2/tree/main/nav2_bt_navigator"
    click B3 "https://github.com/agorarobotics/navigation2/tree/main/nav2_behaviors"

    %% Click Events for Infrastructure & Middleware
    click I1 "https://github.com/agorarobotics/navigation2/tree/main/nav2_lifecycle_manager"
    click I2 "https://github.com/agorarobotics/navigation2/tree/main/nav2_util"
    click I3 "https://github.com/agorarobotics/navigation2/tree/main/nav2_docking"
    click I4 "https://github.com/agorarobotics/navigation2/tree/main/nav2_msgs"
    click I5 "https://github.com/agorarobotics/navigation2/tree/main/nav2_core"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef pipeline fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef behavior fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef infra fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef plugin fill:#e2e3e5,stroke:#333,stroke-width:2px;
```
