# shreyasjb112007-stack/arachnid architecture
> Architecture diagram of the GitHub repository shreyasjb112007-stack/arachnid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/shreyasjb112007-stack/arachnid
- Repository: https://github.com/shreyasjb112007-stack/arachnid
## Overview
ARACHNID is a rover platform whose current runtime is a React mission-control UI and FastAPI backend, connected over Wi-Fi TCP to the rover’s ESP32 hardware. The main workflow runs from operator commands or sensor telemetry, through backend safety, state and hardware services, to motor commands or live map/telemetry updates in the UI. Backend autonomy adds pose estimation, mapping, exploration and planning; the README also documents a separate legacy ROS 2 stack. Relationships in the production graph are limited to those supported by excerpts or README statements; the ROS 2 branch is documented but not wired into the current runtime.
Main entry points: [`software/backend/autonomy/engine.py`](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/engine.py) (Autonomy Engine), [`software/backend/hardware/gateway.py`](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/hardware/gateway.py) (Hardware Gateway), [`software/frontend/src/hooks/useRover.tsx`](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/hooks/useRover.tsx) (Rover State Hook), [`software/backend/main.py`](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/main.py) (Backend Application)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_ui["Mission Control UI"]
node_frontend["Mission Control App
[App.tsx]"]
node_rover_hook["Rover State Hook
[useRover.tsx]"]
node_api_client["HTTP API Client
[api.ts]"]
node_ws_client["WebSocket Client
[websocket.ts]"]
node_live_map["Live Map
[LiveMap.tsx]"]
node_dashboard["Dashboard View
[DashboardPage.tsx]"]
end
subgraph group_backend["Backend Runtime"]
node_schemas["Data Schemas
[schemas.py]"]
node_routes["HTTP API Routes
[routes.py]"]
node_state["Rover State
[rover_state.py]"]
node_safety["Safety Manager
[manager.py]"]
node_gateway["Hardware Gateway
[gateway.py]"]
node_adapters["Hardware Adapters
[adapters.py]"]
node_sim_engine["Simulator Engine
[engine.py]"]
node_ws_manager["WebSocket Manager
[manager.py]"]
node_entry["Backend Application
[main.py]"]
end
subgraph group_autonomy["Autonomy and Mapping"]
node_autonomy_engine["Autonomy Engine
[engine.py]"]
node_pose_estimator["Pose Estimator
[pose_estimator.py]"]
node_mapper["Global Mapper
[mapper.py]"]
node_planner["Path Planner
[planner.py]"]
node_explorer["Frontier Explorer
[explorer.py]"]
end
subgraph group_hardware["Rover Hardware"]
node_brain["Brain ESP32"]
node_rover_mcu["Drive ESP32"]
node_motors["Motor Drivers"]
end
subgraph group_legacy["Legacy ROS 2"]
node_ros_mapping["ROS Occupancy Mapping"]
node_ros_exploration["ROS Frontier Exploration"]
node_ros_navigation["ROS Navigation Planner
[planner_node.py]"]
node_ros_odometry["ROS Odometry
[odometry_node.py]"]
node_ros_velocity["ROS Velocity Control"]
node_ros_motor["ROS Motor Bridge"]
node_ros_sensors["ROS Sensor Interface
[sensor_node.py]"]
node_ros_localization["ROS Localization"]
end
node_operator(("Operator"))
node_operator -->|"operates"| node_frontend
node_frontend -->|"provides context"| node_rover_hook
node_frontend -->|"renders"| node_live_map
node_dashboard -->|"reads state"| node_rover_hook
node_live_map -->|"reads map"| node_rover_hook
node_rover_hook -->|"requests data"| node_api_client
node_rover_hook -->|"subscribes to events"| node_ws_client
node_operator -.->|"issues commands"| node_rover_hook
node_entry -->|"registers routes"| node_routes
node_entry -->|"starts gateway"| node_gateway
node_entry -->|"starts autonomy"| node_autonomy_engine
node_entry -->|"manages socket clients"| node_ws_manager
node_routes -->|"validates commands"| node_safety
node_routes -->|"reads status"| node_state
node_routes -->|"sends commands"| node_gateway
node_safety -->|"checks and updates"| node_state
node_gateway -->|"uses adapters"| node_adapters
node_gateway -->|"updates state"| node_state
node_gateway -->|"broadcasts telemetry"| node_ws_manager
node_sim_engine -->|"implements provider"| node_adapters
node_rover_hook -->|"HTTP requests"| node_routes
node_ws_client -->|"opens WebSocket"| node_entry
node_entry -->|"broadcasts events"| node_ws_manager
node_autonomy_engine -->|"uses estimator"| node_pose_estimator
node_autonomy_engine -->|"updates map"| node_mapper
node_autonomy_engine -->|"plans paths"| node_planner
node_autonomy_engine -->|"selects frontiers"| node_explorer
node_autonomy_engine -->|"reads status"| node_state
node_autonomy_engine -->|"sends commands"| node_gateway
node_autonomy_engine -->|"publishes updates"| node_ws_manager
node_gateway -->|"Wi-Fi TCP telemetry and commands"| node_brain
node_brain -->|"relays UART commands"| node_rover_mcu
node_rover_mcu -->|"drives"| node_motors
node_ros_odometry -->|"provides encoder math"| node_ros_velocity
node_ros_mapping -.->|"publishes map input"| node_ros_exploration
node_ros_exploration -.->|"publishes frontier targets"| node_ros_navigation
node_ros_navigation -.->|"uses path control"| node_ros_velocity
node_ros_sensors -.->|"supplies sensor data"| node_ros_mapping
node_ros_localization -.->|"supplies pose"| node_ros_navigation
node_ros_velocity -.->|"sends velocity commands"| node_ros_motor
click node_frontend "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/App.tsx"
click node_rover_hook "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/hooks/useRover.tsx"
click node_api_client "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/services/api.ts"
click node_ws_client "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/services/websocket.ts"
click node_live_map "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/components/LiveMap.tsx"
click node_dashboard "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/pages/DashboardPage.tsx"
click node_schemas "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/models/schemas.py"
click node_routes "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/api/routes.py"
click node_state "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/services/rover_state.py"
click node_safety "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/safety/manager.py"
click node_gateway "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/hardware/gateway.py"
click node_adapters "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/hardware/adapters.py"
click node_sim_engine "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/hardware/simulator/engine.py"
click node_ws_manager "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/websocket/manager.py"
click node_entry "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/main.py"
click node_autonomy_engine "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/engine.py"
click node_pose_estimator "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/pose_estimator.py"
click node_mapper "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/mapper.py"
click node_planner "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/planner.py"
click node_explorer "https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/explorer.py"
click node_ros_mapping "https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/mapping/mapping/occupancy_grid_node.py"
click node_ros_exploration "https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/exploration/exploration/exploration_manager.py"
click node_ros_navigation "https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/navigation/navigation/planner_node.py"
click node_ros_odometry "https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/odometry/odometry/odometry_node.py"
click node_ros_velocity "https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/navigation/navigation/velocity_controller.py"
click node_ros_motor "https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/motor_bridge/motor_bridge/motor_bridge_node.py"
click node_ros_sensors "https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/sensor_interface/sensor_interface/sensor_node.py"
click node_ros_localization "https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/localization/localization/localization_node.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_frontend,node_rover_hook,node_api_client,node_ws_client,node_live_map,node_dashboard toneBlue
class node_schemas,node_routes,node_state,node_safety,node_gateway,node_adapters,node_sim_engine,node_ws_manager,node_entry toneAmber
class node_autonomy_engine,node_pose_estimator,node_mapper,node_planner,node_explorer toneMint
class node_brain,node_rover_mcu,node_motors toneRose
class node_ros_mapping,node_ros_exploration,node_ros_navigation,node_ros_odometry,node_ros_velocity,node_ros_motor,node_ros_sensors,node_ros_localization,node_operator toneIndigo
```
## Components
### Mission Control UI
- [Mission Control App](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/App.tsx): `software/frontend/src/App.tsx`
- [Rover State Hook](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/hooks/useRover.tsx): `software/frontend/src/hooks/useRover.tsx`
- [HTTP API Client](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/services/api.ts): `software/frontend/src/services/api.ts`
- [WebSocket Client](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/services/websocket.ts): `software/frontend/src/services/websocket.ts`
- [Live Map](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/components/LiveMap.tsx): `software/frontend/src/components/LiveMap.tsx`
- [Dashboard View](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/frontend/src/pages/DashboardPage.tsx): `software/frontend/src/pages/DashboardPage.tsx`
### Backend Runtime
- [Data Schemas](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/models/schemas.py): `software/backend/models/schemas.py`
- [HTTP API Routes](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/api/routes.py): `software/backend/api/routes.py`
- [Rover State](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/services/rover_state.py): `software/backend/services/rover_state.py`
- [Safety Manager](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/safety/manager.py): `software/backend/safety/manager.py`
- [Hardware Gateway](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/hardware/gateway.py): `software/backend/hardware/gateway.py`
- [Hardware Adapters](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/hardware/adapters.py): `software/backend/hardware/adapters.py`
- [Simulator Engine](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/hardware/simulator/engine.py): `software/backend/hardware/simulator/engine.py`
- [WebSocket Manager](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/websocket/manager.py): `software/backend/websocket/manager.py`
- [Backend Application](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/main.py): `software/backend/main.py`
### Autonomy and Mapping
- [Autonomy Engine](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/engine.py): `software/backend/autonomy/engine.py`
- [Pose Estimator](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/pose_estimator.py): `software/backend/autonomy/pose_estimator.py`
- [Global Mapper](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/mapper.py): `software/backend/autonomy/mapper.py`
- [Path Planner](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/planner.py): `software/backend/autonomy/planner.py`
- [Frontier Explorer](https://github.com/shreyasjb112007-stack/arachnid/blob/main/software/backend/autonomy/explorer.py): `software/backend/autonomy/explorer.py`
### Rover Hardware
- **Brain ESP32**
- **Drive ESP32**
- **Motor Drivers**
### Legacy ROS 2
- [ROS Occupancy Mapping](https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/mapping/mapping/occupancy_grid_node.py): `ros2_ws/src/mapping/mapping/occupancy_grid_node.py`
- [ROS Frontier Exploration](https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/exploration/exploration/exploration_manager.py): `ros2_ws/src/exploration/exploration/exploration_manager.py`
- [ROS Navigation Planner](https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/navigation/navigation/planner_node.py): `ros2_ws/src/navigation/navigation/planner_node.py`
- [ROS Odometry](https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/odometry/odometry/odometry_node.py): `ros2_ws/src/odometry/odometry/odometry_node.py`
- [ROS Velocity Control](https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/navigation/navigation/velocity_controller.py): `ros2_ws/src/navigation/navigation/velocity_controller.py`
- [ROS Motor Bridge](https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/motor_bridge/motor_bridge/motor_bridge_node.py): `ros2_ws/src/motor_bridge/motor_bridge/motor_bridge_node.py`
- [ROS Sensor Interface](https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/sensor_interface/sensor_interface/sensor_node.py): `ros2_ws/src/sensor_interface/sensor_interface/sensor_node.py`
- [ROS Localization](https://github.com/shreyasjb112007-stack/arachnid/blob/main/ros2_ws/src/localization/localization/localization_node.py): `ros2_ws/src/localization/localization/localization_node.py`
### Other components
- **Operator**
## Connections
- Operator → Mission Control App: operates (evidence: `README.md`)
- Mission Control App → Rover State Hook: provides context (evidence: `software/frontend/src/App.tsx`)
- Mission Control App → Live Map: renders (evidence: `software/frontend/src/App.tsx`)
- Dashboard View → Rover State Hook: reads state (evidence: `software/frontend/src/pages/DashboardPage.tsx`)
- Live Map → Rover State Hook: reads map (evidence: `software/frontend/src/components/LiveMap.tsx`)
- Rover State Hook → HTTP API Client: requests data (evidence: `software/frontend/src/hooks/useRover.tsx`)
- Rover State Hook → WebSocket Client: subscribes to events (evidence: `software/frontend/src/hooks/useRover.tsx`)
- Operator → Rover State Hook: issues commands
- Backend Application → HTTP API Routes: registers routes (evidence: `software/backend/main.py`)
- Backend Application → Hardware Gateway: starts gateway (evidence: `software/backend/main.py`)
- Backend Application → Autonomy Engine: starts autonomy (evidence: `software/backend/main.py`)
- Backend Application → WebSocket Manager: manages socket clients (evidence: `software/backend/main.py`)
- HTTP API Routes → Safety Manager: validates commands (evidence: `software/backend/api/routes.py`)
- HTTP API Routes → Rover State: reads status (evidence: `software/backend/api/routes.py`)
- HTTP API Routes → Hardware Gateway: sends commands (evidence: `software/backend/api/routes.py`)
- Safety Manager → Rover State: checks and updates (evidence: `software/backend/safety/manager.py`)
- Hardware Gateway → Hardware Adapters: uses adapters (evidence: `software/backend/hardware/gateway.py`)
- Hardware Gateway → Rover State: updates state (evidence: `software/backend/hardware/gateway.py`)
- Hardware Gateway → WebSocket Manager: broadcasts telemetry (evidence: `software/backend/hardware/gateway.py`)
- Simulator Engine → Hardware Adapters: implements provider (evidence: `software/backend/hardware/simulator/engine.py`)
- Rover State Hook → HTTP API Routes: HTTP requests (evidence: `README.md`)
- WebSocket Client → Backend Application: opens WebSocket (evidence: `README.md`)
- Backend Application → WebSocket Manager: broadcasts events (evidence: `software/backend/main.py`)
- Autonomy Engine → Pose Estimator: uses estimator (evidence: `software/backend/autonomy/engine.py`)
- Autonomy Engine → Global Mapper: updates map (evidence: `software/backend/autonomy/engine.py`)
- Autonomy Engine → Path Planner: plans paths (evidence: `software/backend/autonomy/engine.py`)
- Autonomy Engine → Frontier Explorer: selects frontiers (evidence: `software/backend/autonomy/engine.py`)
- Autonomy Engine → Rover State: reads status (evidence: `software/backend/autonomy/engine.py`)
- Autonomy Engine → Hardware Gateway: sends commands (evidence: `software/backend/autonomy/engine.py`)
- Autonomy Engine → WebSocket Manager: publishes updates (evidence: `software/backend/autonomy/engine.py`)
- Hardware Gateway → Brain ESP32: Wi-Fi TCP telemetry and commands (evidence: `README.md`)
- Brain ESP32 → Drive ESP32: relays UART commands (evidence: `README.md`)
- Drive ESP32 → Motor Drivers: drives (evidence: `README.md`)
- ROS Odometry → ROS Velocity Control: provides encoder math (evidence: `ros2_ws/src/navigation/navigation/velocity_controller.py`)
- ROS Occupancy Mapping → ROS Frontier Exploration: publishes map input
- ROS Frontier Exploration → ROS Navigation Planner: publishes frontier targets
- ROS Navigation Planner → ROS Velocity Control: uses path control
- ROS Sensor Interface → ROS Occupancy Mapping: supplies sensor data
- ROS Localization → ROS Navigation Planner: supplies pose
- ROS Velocity Control → ROS Motor Bridge: sends velocity commands