# open-rmf/rmf_traffic architecture

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

- Interactive diagram: https://gitdiagram.com/open-rmf/rmf_traffic
- Repository: https://github.com/open-rmf/rmf_traffic

## Overview

##### Project type and purpose
- This is a C++ library (ROS2 package) named rmf_traffic. Its purpose is to provide core algorithms and data structures for scheduling, routing, and negotiating mobile-robot traffic among multiple agents in an RMF (Robotics Middleware Framework) system.

##### File structure
- Top-level directories:
- src/rmf_traffic – Implementation mirroring the public API structure.
- thirdparty/fcl – A third-party collision‐detection library (used by geometry & blockade modules).
- docs – Sphinx/Doxygen build for API docs.
- test – Unit and regression tests organized per sub‐module.
- rmf_traffic_examples – Example ROS2 nodes illustrating use.
- CMakeLists.txt / package.xml / colcon.pkg – Build and packaging scripts (ROS2 + CMake).

##### Key insights from README
- The package exposes an API (ROS2 compliant) for:
- Scheduling robot itineraries
- Negotiating traffic conflicts (both path‐based & area‐based)
- Spatial queries & trajectory generation
- External dependency: FCL for collision geometry.

1. Public API Layer
– Entry point for clients (ROS2 nodes, examples)
– Headers in include/rmf_traffic
2. Core Modules
– Scheduler (schedule::Database, Participant, Query, Viewer)
– Negotiation
- agv::Negotiator, Schedule::Negotiator, blockade::Moderator
– Planner (agv::Planner, Rollout, Graph)
– Blockade Manager (blockade::Participant, Rectifier)
– Geometry Engine (ConvexShape, Circle, Space)
3. Utility & Debug
– detail namespaces, debug plumbing
4. Third-Party Collision Library
– FCL (broadphase & narrowphase collision detection)
5. Example Clients & Tests
– rmf_traffic_examples
– test harness

- Client code → Public API Layer → Core Modules
- Planner ↔ Geometry Engine (for spatial queries & path interpolation)
- Core Modules → FCL (calls into collision detection for blockade & negotiation)
- Scheduler & Negotiator ↔ Schedule Database (read/write itineraries)
- Blockade Manager ←→ Schedule Database (to track area bookmarks & conflicts)

c. Architectural patterns & design principles
- Layered architecture: API → core domain modules → low-level utilities → external libs
- Separation of concerns:
- Scheduling vs. negotiation vs. geometry vs. planning vs. blockade
- Public API vs. internal detail namespace
- Plugin-like extensibility: algorithms in agv/planning can be swapped (A*, heuristics)

d. Technologies & frameworks
– C++17, CMake, ROS2 (colcon build), FCL (collision library), Doxygen/Sphinx

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Public API Layer
    subgraph "Public API Layer"
        API["Public API"]:::public
    end

    %% Core Modules
    subgraph "Core Modules"
        subgraph Scheduler
            ScheduleAPI["Scheduler Module"]:::core
        end
        subgraph Negotiation
            AGVNeg["AGV SimpleNegotiator"]:::core
            ScheduleNeg["Schedule Negotiator"]:::core
            BlockMod["Blockade Moderator"]:::core
        end
        subgraph Planner
            PlannerAPI["Planner"]:::core
            Graph["Graph"]:::core
            Rollout["Rollout"]:::core
        end
        subgraph BlockadeManager
            Participant["Participant"]:::core
            Rectifier["Rectifier"]:::core
        end
        subgraph GeometryEngine
            Shape["Shape/Convex/Circle/Space"]:::core
        end
        DB["Schedule Database"]:::core
    end

    %% Utility & Debug
    subgraph "Utility & Debug"
        Plumber["Debug Plumber"]:::util
        Detail["Internal Detail"]:::util
    end

    %% External Dependencies
    subgraph "External"
        FCL["FCL Library"]:::external
    end

    %% Clients and Tests
    Clients["Example Client"]:::client
    Tests["Test Harness"]:::client

    %% Data Flows and Relationships
    Clients -->|"use API"| API
    Tests -->|"test API"| API

    API -->|"schedule()"| ScheduleAPI
    API -->|"negotiate_path()"| AGVNeg
    API -->|"negotiate_time()"| ScheduleNeg
    API -->|"moderate_blockade()"| BlockMod
    API -->|"compute_plan()"| PlannerAPI
    API -->|"register_participant()"| Participant
    API -->|"spatial_query()"| Shape

    PlannerAPI -->|"compute_roadmap()"| Graph
    PlannerAPI -->|"sample_trajectories()"| Rollout
    PlannerAPI -->|"spatial_queries"| Shape

    Shape -->|"collision_checks()"| FCL
    AGVNeg -->|"collision_checks()"| FCL
    BlockMod -->|"collision_checks()"| FCL

    ScheduleAPI -->|"read/write"| DB
    ScheduleNeg -->|"read/write"| DB
    Participant -->|"read/write"| DB
    Rectifier -->|"read/write"| DB

    Plumber -.-> ScheduleAPI
    Plumber -.-> PlannerAPI
    Plumber -.-> AGVNeg
    Detail  -.-> ScheduleAPI
    Detail  -.-> PlannerAPI
    Detail  -.-> BlockMod

    %% Click Events
    click API "https://github.com/open-rmf/rmf_traffic/tree/main/rmf_traffic/include/rmf_traffic"
    click ScheduleAPI "https://github.com/open-rmf/rmf_traffic/tree/main/rmf_traffic/include/rmf_traffic/schedule"
    click AGVNeg "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/agv/SimpleNegotiator.hpp"
    click ScheduleNeg "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/schedule/Negotiator.hpp"
    click BlockMod "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/blockade/Moderator.hpp"
    click PlannerAPI "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/agv/Planner.hpp"
    click Graph "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/agv/Graph.hpp"
    click Rollout "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/agv/Rollout.hpp"
    click Participant "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/blockade/Participant.hpp"
    click Rectifier "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/blockade/Rectifier.hpp"
    click Shape "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/geometry/Shape.hpp"
    click Plumber "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic/include/rmf_traffic/debug/Plumber.hpp"
    click Detail "https://github.com/open-rmf/rmf_traffic/tree/main/rmf_traffic/include/rmf_traffic/detail"
    click FCL "https://github.com/open-rmf/rmf_traffic/tree/main/rmf_traffic/thirdparty/fcl"
    click Clients "https://github.com/open-rmf/rmf_traffic/blob/main/rmf_traffic_examples/src/three_robots.cpp"
    click Tests "https://github.com/open-rmf/rmf_traffic/tree/main/rmf_traffic/test"

    %% Styles
    classDef public fill:#D6EAF8,stroke:#217DBB,color:#000
    classDef core fill:#D5F5E3,stroke:#27AE60,color:#000
    classDef external fill:#FAD7A0,stroke:#CA6F1E,color:#000
    classDef util fill:#E5E8E8,stroke:#ABB2B9,color:#000
    classDef client fill:#EBDEF0,stroke:#8E44AD,color:#000
```
