# ros-navigation/navigation2 architecture

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

- Interactive diagram: https://gitdiagram.com/ros-navigation/navigation2
- Repository: https://github.com/ros-navigation/navigation2

## Overview

#### Purpose and runtime
Nav2 is a ROS 2 navigation stack for mobile robots. It is a multi-package C++ system with Python launch/client packages, built with CMake/ament. Nodes communicate through ROS 2 actions, services, topics, TF transforms, lifecycle state, and `nav2_msgs` interfaces. Shared plugin contracts define replaceable planners, controllers, smoothers, behaviors, and navigators: `nav2_core/include/nav2_core/global_planner.hpp`, `nav2_core/include/nav2_core/controller.hpp`, `nav2_msgs/action/NavigateToPose.action`.

#### System entry points and composition
The principal operational entry is the bringup launch layer, which assembles localization, navigation servers, maps, parameters, and lifecycle management: `nav2_bringup/launch/bringup_launch.py`, `nav2_bringup/launch/navigation_launch.py`, `nav2_bringup/params/nav2_params.yaml`. Individual server executables generally enter through package-local `src/main.cpp`, such as `nav2_planner/src/main.cpp` and `nav2_controller/src/main.cpp`. `nav2_lifecycle_manager` controls ordered activation and health/bond management: `nav2_lifecycle_manager/src/lifecycle_manager.cpp`.

#### World model and localization
Map serving supplies occupancy-grid maps and map persistence; map/filter metadata forms the static environment boundary: `nav2_map_server/src/map_server/map_server.cpp`, `nav2_map_server/src/map_io.cpp`, `nav2_bringup/maps/warehouse.yaml`. AMCL provides particle-filter localization from map, laser, and motion inputs: `nav2_amcl/src/amcl_node.cpp`, `nav2_amcl/src/sensors/laser/likelihood_field_model.cpp`. The layered 2D costmap combines static maps and live sensor observations into global/local collision-cost representations; filters can impose keepout or speed zones: `nav2_costmap_2d/src/costmap_2d_ros.cpp`, `nav2_costmap_2d/plugins/obstacle_layer.cpp`, `nav2_costmap_2d/plugins/costmap_filters/keepout_filter.cpp`.

#### Navigation orchestration
`nav2_bt_navigator` accepts high-level navigation actions and executes XML behavior trees. Its trees call planner, controller, smoother, route, behavior, and recovery actions through reusable BT nodes, allowing replanning, cancellation, and recovery policy to be configured rather than hardcoded: `nav2_bt_navigator/src/bt_navigator.cpp`, `nav2_bt_navigator/behavior_trees/navigate_to_pose_w_replanning_and_recovery.xml`, `nav2_behavior_tree/src/behavior_tree_engine.cpp`. The public command boundary is primarily `NavigateToPose`/`NavigateThroughPoses`; Python applications can use `nav2_simple_commander/nav2_simple_commander/robot_navigator.py`.

#### Planning, routing, and smoothing
`nav2_planner` hosts global-planner plugins over the global costmap and exposes path computation/validation: `nav2_planner/src/planner_server.cpp`, `nav2_planner/include/nav2_planner/is_path_valid_service.hpp`. Included algorithms include NavFn, Theta*, and Smac 2D/Hybrid/Lattice planners: `nav2_navfn_planner/src/navfn_planner.cpp`, `nav2_theta_star_planner/src/theta_star_planner.cpp`, `nav2_smac_planner/src/smac_planner_hybrid.cpp`. `nav2_smoother` optionally refines paths before tracking: `nav2_smoother/src/nav2_smoother.cpp`. Separately, `nav2_route` plans and tracks routes on GeoJSON graphs, with pluggable edge scoring and route operations: `nav2_route/src/route_server.cpp`, `nav2_route/src/route_planner.cpp`, `nav2_route/graphs/sample_graph.geojson`.

#### Control, safety, and recovery
`nav2_controller` turns paths, current pose/odometry, and local costmaps into velocity commands via selectable controller, goal-checker, progress-checker, and path-handler plugins: `nav2_controller/src/controller_server.cpp`, `nav2_controller/include/nav2_controller/controller_server.hpp`. Implementations include DWB, MPPI, Regulated Pure Pursuit, Graceful, and rotation-shim controllers: `nav2_dwb_controller/dwb_core/src/dwb_local_planner.cpp`, `nav2_mppi_controller/src/controller.cpp`, `nav2_regulated_pure_pursuit_controller/src/regulated_pure_pursuit_controller.cpp`. Commands may be postprocessed by `nav2_velocity_smoother/src/velocity_smoother.cpp`; the independent collision monitor consumes scan/range/point-cloud sources and can constrain or stop motion: `nav2_collision_monitor/src/collision_monitor_node.cpp`. Recovery behaviors—spin, backup, wait, assisted teleop, drive-on-heading—are action servers invoked by BTs: `nav2_behaviors/src/behavior_server.cpp`.

#### Extensions and operational integrations
Pluginlib XML manifests are the central extension boundary across algorithms and behaviors, e.g. `nav2_costmap_2d/costmap_plugins.xml`, `nav2_mppi_controller/critics.xml`, and `nav2_route/plugins.xml`. Optional application servers cover waypoint tasks, following, and docking: `nav2_waypoint_follower/src/waypoint_follower.cpp`, `nav2_following/opennav_following/src/following_server.cpp`, `nav2_docking/opennav_docking/src/docking_server.cpp`. RViz integrations support operator visualization and route/docking tools: `nav2_rviz_plugins/plugins_description.xml`. Development infrastructure includes Docker/devcontainer support and GitHub/CircleCI workflows: `Dockerfile`, `.devcontainer/devcontainer.json`, `.github/workflows/build_main_against_distros.yml`.

Main entry points: [`nav2_behavior_tree/src/behavior_tree_engine.cpp`](https://github.com/ros-navigation/navigation2/blob/main/nav2_behavior_tree/src/behavior_tree_engine.cpp) (Behavior Tree Engine), [`nav2_controller/src/controller_server.cpp`](https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/src/controller_server.cpp) (Controller Server), [`nav2_map_server/src/map_server/map_server.cpp`](https://github.com/ros-navigation/navigation2/blob/main/nav2_map_server/src/map_server/map_server.cpp) (Map Server), [`nav2_costmap_2d/src/costmap_2d_ros.cpp`](https://github.com/ros-navigation/navigation2/blob/main/nav2_costmap_2d/src/costmap_2d_ros.cpp) (Global & Local Costmaps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_composition["Bringup &amp; Lifecycle"]
  node_client["Python Robot Client<br/>ROS 2 client<br/>[robot_navigator.py]"]
  node_bringup["Bringup Launch<br/>ROS 2 launch<br/>[bringup_launch.py]"]
  node_lifecycle["Lifecycle Manager<br/>lifecycle coordinator"]
end

subgraph group_world["World Model"]
  node_map_data["Map &amp; Filter Metadata<br/>static environment<br/>[warehouse.yaml]"]
  node_map_server["Map Server<br/>ROS 2 server<br/>[map_server.cpp]"]
  node_amcl["AMCL Localization<br/>ROS 2 node<br/>[amcl_node.cpp]"]
  node_costmaps["Global &amp; Local Costmaps<br/>layered costmaps<br/>[costmap_2d_ros.cpp]"]
end

subgraph group_navigation["Navigation Pipeline"]
  node_bt_navigator["BT Navigator<br/>action orchestrator<br/>[bt_navigator.cpp]"]
  node_behavior_trees["Navigation Behavior Trees<br/>BT XML policy"]
  node_bt_engine["Behavior Tree Engine<br/>BT runtime"]
  node_planner["Planner Server<br/>path action server<br/>[planner_server.cpp]"]
  node_smoother["Smoother Server<br/>path action server<br/>[nav2_smoother.cpp]"]
  node_route["Route Server<br/>route action server<br/>[route_server.cpp]"]
end

subgraph group_motion["Motion &amp; Safety"]
  node_controller["Controller Server<br/>velocity action server"]
  node_velocity_smoother["Velocity Smoother<br/>command filter"]
  node_collision_monitor["Collision Monitor<br/>safety node"]
  node_behaviors["Recovery Behaviors<br/>action servers"]
end

subgraph group_extensions["Extensions"]
  node_plugin_contracts{{"Plugin Contracts<br/>C++ interfaces<br/>[global_planner.hpp]"}}
  node_plugin_manifests["Plugin Manifests<br/>pluginlib registry"]
  node_optional_apps["Task Application Servers<br/>optional ROS 2 servers"]
end

node_client -->|"NavigateToPose actions"| node_bt_navigator
node_bringup -->|"launches"| node_map_server
node_bringup -->|"launches"| node_amcl
node_bringup -->|"launches"| node_bt_navigator
node_bringup -->|"configures"| node_lifecycle
node_lifecycle -->|"activates"| node_map_server
node_lifecycle -->|"activates"| node_bt_navigator
node_map_data -->|"map input"| node_map_server
node_map_server -->|"occupancy grid"| node_amcl
node_map_server -->|"static map layer"| node_costmaps
node_amcl -->|"robot pose / TF"| node_costmaps
node_bt_navigator -->|"selects policy"| node_behavior_trees
node_behavior_trees -->|"executed by"| node_bt_engine
node_bt_engine -->|"compute path"| node_planner
node_bt_engine -->|"smooth path"| node_smoother
node_bt_engine -->|"route operations"| node_route
node_bt_engine -->|"follow path"| node_controller
node_bt_engine -->|"recovery actions"| node_behaviors
node_costmaps -->|"global costs"| node_planner
node_costmaps -->|"local costs"| node_controller
node_planner -->|"planned path"| node_smoother
node_smoother -->|"refined path"| node_controller
node_controller -->|"velocity command"| node_velocity_smoother
node_velocity_smoother -->|"smoothed command"| node_collision_monitor
node_plugin_contracts -.->|"planner interface"| node_planner
node_plugin_contracts -.->|"controller interface"| node_controller
node_plugin_manifests -.->|"loads layers and filters"| node_costmaps
node_plugin_manifests -.->|"loads controllers and critics"| node_controller
node_optional_apps -.->|"navigation integration"| node_bt_navigator

click node_client "https://github.com/ros-navigation/navigation2/blob/main/nav2_simple_commander/nav2_simple_commander/robot_navigator.py"
click node_bringup "https://github.com/ros-navigation/navigation2/blob/main/nav2_bringup/launch/bringup_launch.py"
click node_lifecycle "https://github.com/ros-navigation/navigation2/blob/main/nav2_lifecycle_manager/src/lifecycle_manager.cpp"
click node_map_data "https://github.com/ros-navigation/navigation2/blob/main/nav2_bringup/maps/warehouse.yaml"
click node_map_server "https://github.com/ros-navigation/navigation2/blob/main/nav2_map_server/src/map_server/map_server.cpp"
click node_amcl "https://github.com/ros-navigation/navigation2/blob/main/nav2_amcl/src/amcl_node.cpp"
click node_costmaps "https://github.com/ros-navigation/navigation2/blob/main/nav2_costmap_2d/src/costmap_2d_ros.cpp"
click node_bt_navigator "https://github.com/ros-navigation/navigation2/blob/main/nav2_bt_navigator/src/bt_navigator.cpp"
click node_behavior_trees "https://github.com/ros-navigation/navigation2/blob/main/nav2_bt_navigator/behavior_trees/navigate_to_pose_w_replanning_and_recovery.xml"
click node_bt_engine "https://github.com/ros-navigation/navigation2/blob/main/nav2_behavior_tree/src/behavior_tree_engine.cpp"
click node_planner "https://github.com/ros-navigation/navigation2/blob/main/nav2_planner/src/planner_server.cpp"
click node_smoother "https://github.com/ros-navigation/navigation2/blob/main/nav2_smoother/src/nav2_smoother.cpp"
click node_route "https://github.com/ros-navigation/navigation2/blob/main/nav2_route/src/route_server.cpp"
click node_controller "https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/src/controller_server.cpp"
click node_velocity_smoother "https://github.com/ros-navigation/navigation2/blob/main/nav2_velocity_smoother/src/velocity_smoother.cpp"
click node_collision_monitor "https://github.com/ros-navigation/navigation2/blob/main/nav2_collision_monitor/src/collision_monitor_node.cpp"
click node_behaviors "https://github.com/ros-navigation/navigation2/blob/main/nav2_behaviors/src/behavior_server.cpp"
click node_plugin_contracts "https://github.com/ros-navigation/navigation2/blob/main/nav2_core/include/nav2_core/global_planner.hpp"
click node_plugin_manifests "https://github.com/ros-navigation/navigation2/blob/main/nav2_costmap_2d/costmap_plugins.xml"
click node_optional_apps "https://github.com/ros-navigation/navigation2/blob/main/nav2_waypoint_follower/src/waypoint_follower.cpp"

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_client,node_bringup,node_lifecycle toneBlue
class node_map_data,node_map_server,node_amcl,node_costmaps toneAmber
class node_bt_navigator,node_behavior_trees,node_bt_engine,node_planner,node_smoother,node_route toneMint
class node_controller,node_velocity_smoother,node_collision_monitor,node_behaviors toneRose
class node_plugin_contracts,node_plugin_manifests,node_optional_apps toneIndigo
```

## Components

### Bringup & Lifecycle

- [Python Robot Client](https://github.com/ros-navigation/navigation2/blob/main/nav2_simple_commander/nav2_simple_commander/robot_navigator.py): ROS 2 client · `nav2_simple_commander/nav2_simple_commander/robot_navigator.py`
- [Bringup Launch](https://github.com/ros-navigation/navigation2/blob/main/nav2_bringup/launch/bringup_launch.py): ROS 2 launch · Composes localization, navigation servers, maps, and parameters. · `nav2_bringup/launch/bringup_launch.py`
- [Lifecycle Manager](https://github.com/ros-navigation/navigation2/blob/main/nav2_lifecycle_manager/src/lifecycle_manager.cpp): lifecycle coordinator · Orders activation and monitors server health bonds. · `nav2_lifecycle_manager/src/lifecycle_manager.cpp`

### World Model

- [Map & Filter Metadata](https://github.com/ros-navigation/navigation2/blob/main/nav2_bringup/maps/warehouse.yaml): static environment · `nav2_bringup/maps/warehouse.yaml`
- [Map Server](https://github.com/ros-navigation/navigation2/blob/main/nav2_map_server/src/map_server/map_server.cpp): ROS 2 server · Serves occupancy grids and map persistence. · `nav2_map_server/src/map_server/map_server.cpp`
- [AMCL Localization](https://github.com/ros-navigation/navigation2/blob/main/nav2_amcl/src/amcl_node.cpp): ROS 2 node · Estimates robot pose from map, laser, and motion inputs. · `nav2_amcl/src/amcl_node.cpp`
- [Global & Local Costmaps](https://github.com/ros-navigation/navigation2/blob/main/nav2_costmap_2d/src/costmap_2d_ros.cpp): layered costmaps · Combines static maps, observations, and filters into collision costs. · `nav2_costmap_2d/src/costmap_2d_ros.cpp`

### Navigation Pipeline

- [BT Navigator](https://github.com/ros-navigation/navigation2/blob/main/nav2_bt_navigator/src/bt_navigator.cpp): action orchestrator · Runs configurable navigation and recovery behavior trees. · `nav2_bt_navigator/src/bt_navigator.cpp`
- [Navigation Behavior Trees](https://github.com/ros-navigation/navigation2/blob/main/nav2_bt_navigator/behavior_trees/navigate_to_pose_w_replanning_and_recovery.xml): BT XML policy · `nav2_bt_navigator/behavior_trees/navigate_to_pose_w_replanning_and_recovery.xml`
- [Behavior Tree Engine](https://github.com/ros-navigation/navigation2/blob/main/nav2_behavior_tree/src/behavior_tree_engine.cpp): BT runtime · `nav2_behavior_tree/src/behavior_tree_engine.cpp`
- [Planner Server](https://github.com/ros-navigation/navigation2/blob/main/nav2_planner/src/planner_server.cpp): path action server · Hosts global-planner plugins and path validation. · `nav2_planner/src/planner_server.cpp`
- [Smoother Server](https://github.com/ros-navigation/navigation2/blob/main/nav2_smoother/src/nav2_smoother.cpp): path action server · Optionally refines planned paths before tracking. · `nav2_smoother/src/nav2_smoother.cpp`
- [Route Server](https://github.com/ros-navigation/navigation2/blob/main/nav2_route/src/route_server.cpp): route action server · Plans and tracks routes over GeoJSON graphs. · `nav2_route/src/route_server.cpp`

### Motion & Safety

- [Controller Server](https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/src/controller_server.cpp): velocity action server · Tracks paths using controller and checker plugins. · `nav2_controller/src/controller_server.cpp`
- [Velocity Smoother](https://github.com/ros-navigation/navigation2/blob/main/nav2_velocity_smoother/src/velocity_smoother.cpp): command filter · `nav2_velocity_smoother/src/velocity_smoother.cpp`
- [Collision Monitor](https://github.com/ros-navigation/navigation2/blob/main/nav2_collision_monitor/src/collision_monitor_node.cpp): safety node · Independently constrains or stops motion from sensor data. · `nav2_collision_monitor/src/collision_monitor_node.cpp`
- [Recovery Behaviors](https://github.com/ros-navigation/navigation2/blob/main/nav2_behaviors/src/behavior_server.cpp): action servers · Provides spin, backup, wait, teleop, and drive-on-heading actions. · `nav2_behaviors/src/behavior_server.cpp`

### Extensions

- [Plugin Contracts](https://github.com/ros-navigation/navigation2/blob/main/nav2_core/include/nav2_core/global_planner.hpp): C++ interfaces · Defines replaceable navigation algorithm contracts. · `nav2_core/include/nav2_core/global_planner.hpp`
- [Plugin Manifests](https://github.com/ros-navigation/navigation2/blob/main/nav2_costmap_2d/costmap_plugins.xml): pluginlib registry · Registers algorithm, critic, behavior, and route extensions. · `nav2_costmap_2d/costmap_plugins.xml`
- [Task Application Servers](https://github.com/ros-navigation/navigation2/blob/main/nav2_waypoint_follower/src/waypoint_follower.cpp): optional ROS 2 servers · Waypoint following, robot following, and docking integrations. · `nav2_waypoint_follower/src/waypoint_follower.cpp`

## Connections

- Python Robot Client → BT Navigator: NavigateToPose actions
- Bringup Launch → Map Server: launches
- Bringup Launch → AMCL Localization: launches
- Bringup Launch → BT Navigator: launches
- Bringup Launch → Lifecycle Manager: configures
- Lifecycle Manager → Map Server: activates
- Lifecycle Manager → BT Navigator: activates
- Map & Filter Metadata → Map Server: map input
- Map Server → AMCL Localization: occupancy grid
- Map Server → Global & Local Costmaps: static map layer
- AMCL Localization → Global & Local Costmaps: robot pose / TF
- BT Navigator → Navigation Behavior Trees: selects policy
- Navigation Behavior Trees → Behavior Tree Engine: executed by
- Behavior Tree Engine → Planner Server: compute path
- Behavior Tree Engine → Smoother Server: smooth path
- Behavior Tree Engine → Route Server: route operations
- Behavior Tree Engine → Controller Server: follow path
- Behavior Tree Engine → Recovery Behaviors: recovery actions
- Global & Local Costmaps → Planner Server: global costs
- Global & Local Costmaps → Controller Server: local costs
- Planner Server → Smoother Server: planned path
- Smoother Server → Controller Server: refined path
- Controller Server → Velocity Smoother: velocity command
- Velocity Smoother → Collision Monitor: smoothed command
- Plugin Contracts → Planner Server: planner interface
- Plugin Contracts → Controller Server: controller interface
- Plugin Manifests → Global & Local Costmaps: loads layers and filters
- Plugin Manifests → Controller Server: loads controllers and critics
- Task Application Servers → BT Navigator: navigation integration
