# pmvt19/physical_robot architecture

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

- Interactive diagram: https://gitdiagram.com/pmvt19/physical_robot
- Repository: https://github.com/pmvt19/physical_robot

## Overview

SunoBot is an autonomous mobile robot platform. Its user-facing workflows include SLAM and localization, geometric and semantic map creation, planning and navigation to locations, and live sensor monitoring. Robot provides the shared hardware/simulation interface; process runners and planners implement the higher-level workflows. The README documents simulated, physical-local, and server-client modes. Edges are limited to relationships visible in the README or SOURCE INDEX references; several process-level details and the monitoring server’s implementation were not sampled.

Main entry points: [`physical_robot/robot/robot.py`](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/robot/robot.py) (Robot interface), [`archive/run_semantic_slam.py`](https://github.com/pmvt19/physical_robot/blob/main/archive/run_semantic_slam.py) (Semantic SLAM), [`physical_robot/processes/run_semantic_motion_planning.py`](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_semantic_motion_planning.py) (Semantic motion planning), [`physical_robot/models/vlm/ollama_vlm_client.py`](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/models/vlm/ollama_vlm_client.py) (Vision-language models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["Robot workflows"]
  node_slam["SLAM runner<br/>[run_slam.py]"]
  node_semantic_slam["Semantic SLAM"]
  node_semantic_explore["Semantic exploration"]
  node_frontier_explore["Frontier exploration"]
  node_localize["Localization runner"]
end

subgraph group_mapping["Mapping and localization"]
  node_map_builder["Map builder<br/>[map_builder.py]"]
  node_semantic_map_builder["Semantic map builder"]
  node_map["Geometric map<br/>[map.py]"]
  node_advanced_map["Advanced map<br/>[advanced_map.py]"]
  node_semantic_map["Semantic map<br/>[semantic_map.py]"]
  node_particle_filter["Particle localization<br/>[particle_filter.py]"]
  node_icp["ICP alignment<br/>[icp.py]"]
  node_segmentation["Image segmentation"]
  node_vlm["Vision-language models"]
end

subgraph group_planning["Planning and navigation"]
  node_motion_planner["Motion planner<br/>[motion_planner.py]"]
  node_task_planner["Task planner<br/>[task_planner.py]"]
  node_semantic_motion["Semantic motion planning"]
end

subgraph group_robot["Robot and sensors"]
  node_robot["Robot interface<br/>[robot.py]"]
  node_robot_space["Robot space<br/>[robot_space.py]"]
  node_sim_lidar["Simulated lidar<br/>[simulate_lidar.py]"]
  node_motors["Motor controller<br/>[dxl_controller.py]"]
  node_robot_server["RPC server<br/>[robot_server.py]"]
  node_telemetry["Robot sensor telemetry"]
end

subgraph group_monitoring["Monitoring UI"]
  node_monitoring_app["RoboMonitor app<br/>[App.tsx]"]
  node_robot_service["Telemetry WebSocket client<br/>[robotService.ts]"]
  node_ui_server["Telemetry server<br/>[ui_server.py]"]
end

node_operator(("Robot operator"))

node_operator -->|"runs SLAM"| node_slam
node_operator -->|"requests navigation"| node_semantic_motion
node_operator -->|"monitors robot"| node_monitoring_app
node_semantic_slam -->|"uses robot"| node_robot
node_semantic_slam -->|"uses map"| node_map
node_semantic_slam -->|"uses map"| node_advanced_map
node_semantic_slam -->|"uses map"| node_semantic_map
node_semantic_slam -->|"uses vision"| node_segmentation
node_semantic_slam -->|"queries model"| node_vlm
node_semantic_map_builder -->|"uses vision"| node_segmentation
node_semantic_map_builder -->|"queries model"| node_vlm
node_semantic_map_builder -->|"builds map"| node_semantic_map
node_map -->|"aligns scans"| node_icp
node_advanced_map -->|"aligns scans"| node_icp
node_semantic_map -->|"aligns scans"| node_icp
node_particle_filter -->|"simulates readings"| node_sim_lidar
node_slam -.->|"uses robot"| node_robot
node_localize -.->|"uses robot"| node_robot
node_frontier_explore -.->|"uses robot"| node_robot
node_semantic_explore -.->|"uses robot"| node_robot
node_semantic_motion -->|"uses map"| node_semantic_map
node_semantic_motion -->|"uses localization"| node_particle_filter
node_semantic_motion -->|"queries model"| node_vlm
node_semantic_motion -->|"uses robot space"| node_robot_space
node_motion_planner -->|"plans in"| node_robot_space
node_motion_planner -->|"queries model"| node_vlm
node_task_planner -->|"plans in"| node_robot_space
node_task_planner -->|"queries model"| node_vlm
node_robot -->|"reads simulated scans"| node_sim_lidar
node_robot -->|"controls motors"| node_motors
node_monitoring_app -->|"uses telemetry client"| node_robot_service
node_robot_service -->|"connects by WebSocket"| node_ui_server
node_ui_server -->|"publishes readings"| node_telemetry
node_robot -.->|"serves RPC"| node_robot_server

click node_slam "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_slam.py"
click node_semantic_slam "https://github.com/pmvt19/physical_robot/blob/main/archive/run_semantic_slam.py"
click node_semantic_explore "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_semantic_exploration.py"
click node_frontier_explore "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_frontier_exploration.py"
click node_localize "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_localization_robot.py"
click node_map_builder "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/map_builder/map_builder.py"
click node_semantic_map_builder "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/map_builder/semantic_map_builder.py"
click node_map "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/maps/map.py"
click node_advanced_map "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/maps/advanced_map.py"
click node_semantic_map "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/maps/semantic_map.py"
click node_particle_filter "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/algorithms/particle_filter.py"
click node_icp "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/algorithms/icp.py"
click node_segmentation "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/models/segmentation/image_segmentation.py"
click node_vlm "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/models/vlm/ollama_vlm_client.py"
click node_motion_planner "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/motion_planner.py"
click node_task_planner "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/task_planner/task_planner.py"
click node_semantic_motion "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_semantic_motion_planning.py"
click node_robot "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/robot/robot.py"
click node_robot_space "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/robot/robot_space.py"
click node_sim_lidar "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/hardware/sensors/simulated/simulate_lidar.py"
click node_motors "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/hardware/motors/dxl_controller.py"
click node_robot_server "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/robot/robot_server.py"
click node_monitoring_app "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/ui/robomonitor-pro/App.tsx"
click node_robot_service "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/ui/robomonitor-pro/services/robotService.ts"
click node_ui_server "https://github.com/pmvt19/physical_robot/blob/main/physical_robot/ui/ui_server.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_slam,node_semantic_slam,node_semantic_explore,node_frontier_explore,node_localize toneBlue
class node_map_builder,node_semantic_map_builder,node_map,node_advanced_map,node_semantic_map,node_particle_filter,node_icp,node_segmentation,node_vlm toneAmber
class node_motion_planner,node_task_planner,node_semantic_motion toneMint
class node_robot,node_robot_space,node_sim_lidar,node_motors,node_robot_server,node_telemetry toneRose
class node_monitoring_app,node_robot_service,node_ui_server,node_operator toneIndigo
```

## Components

### Robot workflows

- [SLAM runner](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_slam.py): `physical_robot/processes/run_slam.py`
- [Semantic SLAM](https://github.com/pmvt19/physical_robot/blob/main/archive/run_semantic_slam.py): `archive/run_semantic_slam.py`
- [Semantic exploration](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_semantic_exploration.py): `physical_robot/processes/run_semantic_exploration.py`
- [Frontier exploration](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_frontier_exploration.py): `physical_robot/processes/run_frontier_exploration.py`
- [Localization runner](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_localization_robot.py): `physical_robot/processes/run_localization_robot.py`

### Mapping and localization

- [Map builder](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/map_builder/map_builder.py): `physical_robot/map_builder/map_builder.py`
- [Semantic map builder](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/map_builder/semantic_map_builder.py): `physical_robot/map_builder/semantic_map_builder.py`
- [Geometric map](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/maps/map.py): `physical_robot/maps/map.py`
- [Advanced map](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/maps/advanced_map.py): `physical_robot/maps/advanced_map.py`
- [Semantic map](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/maps/semantic_map.py): `physical_robot/maps/semantic_map.py`
- [Particle localization](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/algorithms/particle_filter.py): `physical_robot/algorithms/particle_filter.py`
- [ICP alignment](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/algorithms/icp.py): `physical_robot/algorithms/icp.py`
- [Image segmentation](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/models/segmentation/image_segmentation.py): `physical_robot/models/segmentation/image_segmentation.py`
- [Vision-language models](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/models/vlm/ollama_vlm_client.py): `physical_robot/models/vlm/ollama_vlm_client.py`

### Planning and navigation

- [Motion planner](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/motion_planner.py): `physical_robot/motion_planner.py`
- [Task planner](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/task_planner/task_planner.py): `physical_robot/task_planner/task_planner.py`
- [Semantic motion planning](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/processes/run_semantic_motion_planning.py): `physical_robot/processes/run_semantic_motion_planning.py`

### Robot and sensors

- [Robot interface](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/robot/robot.py): `physical_robot/robot/robot.py`
- [Robot space](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/robot/robot_space.py): `physical_robot/robot/robot_space.py`
- [Simulated lidar](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/hardware/sensors/simulated/simulate_lidar.py): `physical_robot/hardware/sensors/simulated/simulate_lidar.py`
- [Motor controller](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/hardware/motors/dxl_controller.py): `physical_robot/hardware/motors/dxl_controller.py`
- [RPC server](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/robot/robot_server.py): `physical_robot/robot/robot_server.py`
- **Robot sensor telemetry**

### Monitoring UI

- [RoboMonitor app](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/ui/robomonitor-pro/App.tsx): `physical_robot/ui/robomonitor-pro/App.tsx`
- [Telemetry WebSocket client](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/ui/robomonitor-pro/services/robotService.ts): `physical_robot/ui/robomonitor-pro/services/robotService.ts`
- [Telemetry server](https://github.com/pmvt19/physical_robot/blob/main/physical_robot/ui/ui_server.py): `physical_robot/ui/ui_server.py`

### Other components

- **Robot operator**

## Connections

- Robot operator → SLAM runner: runs SLAM (evidence: `README.md`)
- Robot operator → Semantic motion planning: requests navigation (evidence: `README.md`)
- Robot operator → RoboMonitor app: monitors robot (evidence: `README.md`)
- Semantic SLAM → Robot interface: uses robot (evidence: `archive/run_semantic_slam.py`)
- Semantic SLAM → Geometric map: uses map (evidence: `archive/run_semantic_slam.py`)
- Semantic SLAM → Advanced map: uses map (evidence: `archive/run_semantic_slam.py`)
- Semantic SLAM → Semantic map: uses map (evidence: `archive/run_semantic_slam.py`)
- Semantic SLAM → Image segmentation: uses vision (evidence: `archive/run_semantic_slam.py`)
- Semantic SLAM → Vision-language models: queries model (evidence: `archive/run_semantic_slam.py`)
- Semantic map builder → Image segmentation: uses vision (evidence: `physical_robot/map_builder/semantic_map_builder.py`)
- Semantic map builder → Vision-language models: queries model (evidence: `physical_robot/map_builder/semantic_map_builder.py`)
- Semantic map builder → Semantic map: builds map (evidence: `physical_robot/map_builder/semantic_map_builder.py`)
- Geometric map → ICP alignment: aligns scans (evidence: `physical_robot/maps/map.py`)
- Advanced map → ICP alignment: aligns scans (evidence: `physical_robot/maps/advanced_map.py`)
- Semantic map → ICP alignment: aligns scans (evidence: `physical_robot/maps/semantic_map.py`)
- Particle localization → Simulated lidar: simulates readings (evidence: `physical_robot/algorithms/particle_filter.py`)
- SLAM runner → Robot interface: uses robot
- Localization runner → Robot interface: uses robot
- Frontier exploration → Robot interface: uses robot
- Semantic exploration → Robot interface: uses robot
- Semantic motion planning → Semantic map: uses map (evidence: `physical_robot/processes/run_semantic_motion_planning.py`)
- Semantic motion planning → Particle localization: uses localization (evidence: `physical_robot/processes/run_semantic_motion_planning.py`)
- Semantic motion planning → Vision-language models: queries model (evidence: `physical_robot/processes/run_semantic_motion_planning.py`)
- Semantic motion planning → Robot space: uses robot space (evidence: `physical_robot/processes/run_semantic_motion_planning.py`)
- Motion planner → Robot space: plans in (evidence: `physical_robot/motion_planner.py`)
- Motion planner → Vision-language models: queries model (evidence: `physical_robot/motion_planner.py`)
- Task planner → Robot space: plans in (evidence: `physical_robot/task_planner/task_planner.py`)
- Task planner → Vision-language models: queries model (evidence: `physical_robot/task_planner/task_planner.py`)
- Robot interface → Simulated lidar: reads simulated scans (evidence: `physical_robot/robot/robot.py`)
- Robot interface → Motor controller: controls motors (evidence: `physical_robot/robot/robot.py`)
- RoboMonitor app → Telemetry WebSocket client: uses telemetry client (evidence: `physical_robot/ui/robomonitor-pro/App.tsx`)
- Telemetry WebSocket client → Telemetry server: connects by WebSocket (evidence: `README.md`)
- Telemetry server → Robot sensor telemetry: publishes readings (evidence: `README.md`)
- Robot interface → RPC server: serves RPC (evidence: `README.md`)