# kjames3/x3_ws architecture

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

- Interactive diagram: https://gitdiagram.com/kjames3/x3_ws
- Repository: https://github.com/kjames3/x3_ws

## Overview

This is a ROS 2 workspace for operating a Yahboom X3 robot, with a WebSocket control server as the browser-facing entry point. The main workflow is browser commands and telemetry through the server, which interfaces with robot hardware and ROS 2; in ROS 2 mode, navigation, mapping, perception, and safety capabilities support autonomous operation. The README documents the two browser connections and operating modes. Source-index references confirm several server dependencies, but unsampled implementation details limit further call-level links.

Main entry points: [`src/server_x3.py`](https://github.com/kjames3/x3_ws/blob/main/src/server_x3.py) (WebSocket server), [`src/yahboomcar_nav/launch/x3_bringup.launch.py`](https://github.com/kjames3/x3_ws/blob/main/src/yahboomcar_nav/launch/x3_bringup.launch.py) (ROS bringup), [`src/web/main.js`](https://github.com/kjames3/x3_ws/blob/main/src/web/main.js) (Web interface), [`src/nav2_client.py`](https://github.com/kjames3/x3_ws/blob/main/src/nav2_client.py) (Nav2 client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control and interface"]
  node_server["WebSocket server<br/>[server_x3.py]"]
  node_web["Web interface<br/>[main.js]"]
  node_foxglove["Foxglove bridge"]
end

subgraph group_sensing["Sensing and perception"]
  node_oak["OAK-D driver<br/>[oakd_driver.py]"]
  node_oakpub["Camera ROS publisher"]
  node_detector["YOLO detector<br/>[trt_detector.py]"]
  node_people["Person tracking"]
  node_lidarpeople["Lidar tracking"]
  node_velocity["Velocity estimation"]
end

subgraph group_autonomy["Navigation and safety"]
  node_navclient["Nav2 client<br/>[nav2_client.py]"]
  node_frontier["Frontier exploration"]
  node_initialpose["Initial pose"]
  node_mapprior["Map prior<br/>[map_prior.py]"]
  node_cbf["CBF safety filter<br/>[cbf_filter.py]"]
  node_mppi["Pedestrian critic<br/>[dbas_critic.cpp]"]
  node_slam["SLAM stack<br/>[x3_slam.launch.py]"]
  node_navstack["Nav2 stack<br/>[x3_nav2.launch.py]"]
end

subgraph group_platform["Robot platform"]
  node_ros(("ROS 2 graph"))
  node_hardware["Robot hardware"]
  node_drive["Mecanum drivers<br/>[drivers_x3.py]"]
  node_rosmaster["Rosmaster library<br/>[Rosmaster_Lib.py]"]
  node_battery["Battery monitoring<br/>[battery.py]"]
  node_base["ROS base node<br/>[base_node_X3.cpp]"]
  node_bringup["ROS bringup"]
end

node_browser(("Browser operator"))

node_browser -->|"opens interface"| node_web
node_web -->|"WebSocket control"| node_server
node_web -->|"WebSocket maps"| node_foxglove
node_server -->|"uses drivers"| node_drive
node_drive -->|"delegates to"| node_rosmaster
node_server -->|"uses camera"| node_oak
node_server -->|"uses publisher"| node_oakpub
node_server -->|"uses detector"| node_detector
node_server -->|"uses tracker"| node_people
node_server -->|"uses tracker"| node_lidarpeople
node_server -->|"uses estimator"| node_velocity
node_server -->|"uses battery"| node_battery
node_server -->|"uses client"| node_navclient
node_server -->|"uses explorer"| node_frontier
node_server -->|"uses filter"| node_cbf
node_server -->|"hardware I/O"| node_hardware
node_server -->|"ROS 2 interface"| node_ros
node_foxglove -->|"streams map scan"| node_ros
node_bringup -.->|"starts drivers"| node_base
node_bringup -.->|"starts SLAM"| node_slam
node_bringup -.->|"starts navigation"| node_navstack
node_navclient -.->|"sends goals"| node_navstack
node_mapprior -->|"provides prior"| node_initialpose
node_mppi -->|"subscribes pedestrian data"| node_ros

click node_server "https://github.com/kjames3/x3_ws/blob/main/src/server_x3.py"
click node_web "https://github.com/kjames3/x3_ws/blob/main/src/web/main.js"
click node_drive "https://github.com/kjames3/x3_ws/blob/main/src/drivers_x3.py"
click node_rosmaster "https://github.com/kjames3/x3_ws/blob/main/src/Rosmaster_Lib.py"
click node_oak "https://github.com/kjames3/x3_ws/blob/main/src/oakd_driver.py"
click node_oakpub "https://github.com/kjames3/x3_ws/blob/main/src/oakd_ros_publisher.py"
click node_detector "https://github.com/kjames3/x3_ws/blob/main/src/trt_detector.py"
click node_people "https://github.com/kjames3/x3_ws/blob/main/src/c3_person_tracker.py"
click node_lidarpeople "https://github.com/kjames3/x3_ws/blob/main/src/lidar_person_tracker.py"
click node_velocity "https://github.com/kjames3/x3_ws/blob/main/src/velocity_estimator.py"
click node_battery "https://github.com/kjames3/x3_ws/blob/main/src/battery.py"
click node_navclient "https://github.com/kjames3/x3_ws/blob/main/src/nav2_client.py"
click node_frontier "https://github.com/kjames3/x3_ws/blob/main/src/frontier_explorer.py"
click node_initialpose "https://github.com/kjames3/x3_ws/blob/main/src/auto_initial_pose.py"
click node_mapprior "https://github.com/kjames3/x3_ws/blob/main/src/map_prior.py"
click node_cbf "https://github.com/kjames3/x3_ws/blob/main/src/cbf_filter.py"
click node_mppi "https://github.com/kjames3/x3_ws/blob/main/src/nav2_mppi_dbas_controller/src/dbas_critic.cpp"
click node_base "https://github.com/kjames3/x3_ws/blob/main/src/yahboomcar_base_node/src/base_node_X3.cpp"
click node_bringup "https://github.com/kjames3/x3_ws/blob/main/src/yahboomcar_nav/launch/x3_bringup.launch.py"
click node_slam "https://github.com/kjames3/x3_ws/blob/main/src/yahboomcar_nav/launch/x3_slam.launch.py"
click node_navstack "https://github.com/kjames3/x3_ws/blob/main/src/yahboomcar_nav/launch/x3_nav2.launch.py"

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_server,node_web,node_foxglove,node_browser toneBlue
class node_oak,node_oakpub,node_detector,node_people,node_lidarpeople,node_velocity toneAmber
class node_navclient,node_frontier,node_initialpose,node_mapprior,node_cbf,node_mppi,node_slam,node_navstack toneMint
class node_ros,node_hardware,node_drive,node_rosmaster,node_battery,node_base,node_bringup toneRose
```

## Components

### Control and interface

- [WebSocket server](https://github.com/kjames3/x3_ws/blob/main/src/server_x3.py): `src/server_x3.py`
- [Web interface](https://github.com/kjames3/x3_ws/blob/main/src/web/main.js): `src/web/main.js`
- **Foxglove bridge**

### Sensing and perception

- [OAK-D driver](https://github.com/kjames3/x3_ws/blob/main/src/oakd_driver.py): `src/oakd_driver.py`
- [Camera ROS publisher](https://github.com/kjames3/x3_ws/blob/main/src/oakd_ros_publisher.py): `src/oakd_ros_publisher.py`
- [YOLO detector](https://github.com/kjames3/x3_ws/blob/main/src/trt_detector.py): `src/trt_detector.py`
- [Person tracking](https://github.com/kjames3/x3_ws/blob/main/src/c3_person_tracker.py): `src/c3_person_tracker.py`
- [Lidar tracking](https://github.com/kjames3/x3_ws/blob/main/src/lidar_person_tracker.py): `src/lidar_person_tracker.py`
- [Velocity estimation](https://github.com/kjames3/x3_ws/blob/main/src/velocity_estimator.py): `src/velocity_estimator.py`

### Navigation and safety

- [Nav2 client](https://github.com/kjames3/x3_ws/blob/main/src/nav2_client.py): `src/nav2_client.py`
- [Frontier exploration](https://github.com/kjames3/x3_ws/blob/main/src/frontier_explorer.py): `src/frontier_explorer.py`
- [Initial pose](https://github.com/kjames3/x3_ws/blob/main/src/auto_initial_pose.py): `src/auto_initial_pose.py`
- [Map prior](https://github.com/kjames3/x3_ws/blob/main/src/map_prior.py): `src/map_prior.py`
- [CBF safety filter](https://github.com/kjames3/x3_ws/blob/main/src/cbf_filter.py): `src/cbf_filter.py`
- [Pedestrian critic](https://github.com/kjames3/x3_ws/blob/main/src/nav2_mppi_dbas_controller/src/dbas_critic.cpp): `src/nav2_mppi_dbas_controller/src/dbas_critic.cpp`
- [SLAM stack](https://github.com/kjames3/x3_ws/blob/main/src/yahboomcar_nav/launch/x3_slam.launch.py): `src/yahboomcar_nav/launch/x3_slam.launch.py`
- [Nav2 stack](https://github.com/kjames3/x3_ws/blob/main/src/yahboomcar_nav/launch/x3_nav2.launch.py): `src/yahboomcar_nav/launch/x3_nav2.launch.py`

### Robot platform

- **ROS 2 graph**
- **Robot hardware**
- [Mecanum drivers](https://github.com/kjames3/x3_ws/blob/main/src/drivers_x3.py): `src/drivers_x3.py`
- [Rosmaster library](https://github.com/kjames3/x3_ws/blob/main/src/Rosmaster_Lib.py): `src/Rosmaster_Lib.py`
- [Battery monitoring](https://github.com/kjames3/x3_ws/blob/main/src/battery.py): `src/battery.py`
- [ROS base node](https://github.com/kjames3/x3_ws/blob/main/src/yahboomcar_base_node/src/base_node_X3.cpp): `src/yahboomcar_base_node/src/base_node_X3.cpp`
- [ROS bringup](https://github.com/kjames3/x3_ws/blob/main/src/yahboomcar_nav/launch/x3_bringup.launch.py): `src/yahboomcar_nav/launch/x3_bringup.launch.py`

### Other components

- **Browser operator**

## Connections

- Browser operator → Web interface: opens interface
- Web interface → WebSocket server: WebSocket control
- Web interface → Foxglove bridge: WebSocket maps
- WebSocket server → Mecanum drivers: uses drivers (evidence: `src/server_x3.py`)
- Mecanum drivers → Rosmaster library: delegates to (evidence: `src/drivers_x3.py`)
- WebSocket server → OAK-D driver: uses camera (evidence: `src/server_x3.py`)
- WebSocket server → Camera ROS publisher: uses publisher (evidence: `src/server_x3.py`)
- WebSocket server → YOLO detector: uses detector (evidence: `src/server_x3.py`)
- WebSocket server → Person tracking: uses tracker (evidence: `src/server_x3.py`)
- WebSocket server → Lidar tracking: uses tracker (evidence: `src/server_x3.py`)
- WebSocket server → Velocity estimation: uses estimator (evidence: `src/server_x3.py`)
- WebSocket server → Battery monitoring: uses battery (evidence: `src/server_x3.py`)
- WebSocket server → Nav2 client: uses client (evidence: `src/server_x3.py`)
- WebSocket server → Frontier exploration: uses explorer (evidence: `src/server_x3.py`)
- WebSocket server → CBF safety filter: uses filter (evidence: `src/server_x3.py`)
- WebSocket server → Robot hardware: hardware I/O
- WebSocket server → ROS 2 graph: ROS 2 interface
- Foxglove bridge → ROS 2 graph: streams map scan
- ROS bringup → ROS base node: starts drivers
- ROS bringup → SLAM stack: starts SLAM
- ROS bringup → Nav2 stack: starts navigation
- Nav2 client → Nav2 stack: sends goals
- Map prior → Initial pose: provides prior (evidence: `src/map_prior.py`)
- Pedestrian critic → ROS 2 graph: subscribes pedestrian data (evidence: `src/nav2_mppi_dbas_controller/src/dbas_critic.cpp`)
