# deepmodeling/uni-lab-os architecture

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

- Interactive diagram: https://gitdiagram.com/deepmodeling/uni-lab-os
- Repository: https://github.com/deepmodeling/uni-lab-os

## Overview

Uni-Lab-OS is a laboratory automation platform: it configures a lab system, connects device drivers and resources, and runs experimental workflows across equipment. Its documented capabilities include multiple protocols and cloud connectivity. The sampled startup code loads configuration and a device graph, and the sampled web controller dispatches action goals to a host node. Other major subsystems are represented from the README and file tree; their internal wiring is not asserted where source was not sampled.

Main entry points: [`unilabos/app/main.py`](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/app/main.py) (System launcher), [`unilabos/ros/nodes/presets/host_node.py`](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/ros/nodes/presets/host_node.py) (Host node), [`unilabos/ros/nodes/base_device_node.py`](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/ros/nodes/base_device_node.py) (Device nodes), [`unilabos/devices`](https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/devices) (Equipment drivers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["System startup"]
  node_entry["System launcher<br/>[main.py]"]
  node_configuration["Configuration<br/>[config.py]"]
end

subgraph group_workflow["Experiment workflows"]
  node_workflow_input["Workflow conversion"]
  node_protocols["Protocol compilers"]
end

subgraph group_runtime["Device runtime"]
  node_host["Host node<br/>[host_node.py]"]
  node_device_nodes["Device nodes"]
  node_device_drivers["Equipment drivers"]
  node_communications["Device communications"]
  node_registry["Device registry<br/>[registry.py]"]
end

subgraph group_resources["Lab resources"]
  node_resource_model["Resource tracking"]
  node_mesh_manager["Resource visualization"]
end

subgraph group_interfaces["User and cloud interfaces"]
  node_web_controller["Action controller<br/>[controller.py]"]
  node_web_api["Web API<br/>[api.py]"]
  node_workflow_reports["Workstation reports"]
end

node_operator(("Operator"))
node_cloud(("Cloud services"))

node_operator -->|"starts system"| node_entry
node_entry -->|"loads config"| node_configuration
node_operator -->|"requests control"| node_web_api
node_web_api -->|"routes requests"| node_web_controller
node_web_controller -->|"sends action goal"| node_host
node_host -->|"manages devices"| node_device_nodes
node_device_nodes -->|"invokes drivers"| node_device_drivers
node_device_drivers -->|"uses interfaces"| node_communications
node_entry -->|"loads device system"| node_registry
node_entry -->|"loads resource graph"| node_resource_model
node_mesh_manager -->|"publishes resource poses"| node_resource_model
node_operator -->|"provides workflow"| node_workflow_input
node_workflow_reports -.->|"reports completion"| node_cloud
node_entry -.->|"requests remote resources"| node_cloud

click node_entry "https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/app/main.py"
click node_configuration "https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/config/config.py"
click node_workflow_input "https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/workflow"
click node_protocols "https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/compile"
click node_web_controller "https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/app/web/controller.py"
click node_host "https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/ros/nodes/presets/host_node.py"
click node_device_nodes "https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/ros/nodes/base_device_node.py"
click node_device_drivers "https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/devices"
click node_communications "https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/device_comms"
click node_registry "https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/registry/registry.py"
click node_resource_model "https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/resources"
click node_mesh_manager "https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/ros/nodes/presets/resource_mesh_manager.py"
click node_web_api "https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/app/web/api.py"
click node_workflow_reports "https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/devices/workstation/workstation_http_service.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_entry,node_configuration toneBlue
class node_workflow_input,node_protocols toneAmber
class node_host,node_device_nodes,node_device_drivers,node_communications,node_registry toneMint
class node_resource_model,node_mesh_manager toneRose
class node_web_controller,node_web_api,node_workflow_reports,node_operator,node_cloud toneIndigo
```

## Components

### System startup

- [System launcher](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/app/main.py): `unilabos/app/main.py`
- [Configuration](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/config/config.py): `unilabos/config/config.py`

### Experiment workflows

- [Workflow conversion](https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/workflow): `unilabos/workflow`
- [Protocol compilers](https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/compile): `unilabos/compile`

### Device runtime

- [Host node](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/ros/nodes/presets/host_node.py): `unilabos/ros/nodes/presets/host_node.py`
- [Device nodes](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/ros/nodes/base_device_node.py): `unilabos/ros/nodes/base_device_node.py`
- [Equipment drivers](https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/devices): `unilabos/devices`
- [Device communications](https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/device_comms): `unilabos/device_comms`
- [Device registry](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/registry/registry.py): `unilabos/registry/registry.py`

### Lab resources

- [Resource tracking](https://github.com/deepmodeling/uni-lab-os/tree/main/unilabos/resources): `unilabos/resources`
- [Resource visualization](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/ros/nodes/presets/resource_mesh_manager.py): `unilabos/ros/nodes/presets/resource_mesh_manager.py`

### User and cloud interfaces

- [Action controller](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/app/web/controller.py): `unilabos/app/web/controller.py`
- [Web API](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/app/web/api.py): `unilabos/app/web/api.py`
- [Workstation reports](https://github.com/deepmodeling/uni-lab-os/blob/main/unilabos/devices/workstation/workstation_http_service.py): `unilabos/devices/workstation/workstation_http_service.py`

### Other components

- **Operator**
- **Cloud services**

## Connections

- Operator → System launcher: starts system
- System launcher → Configuration: loads config
- Operator → Web API: requests control
- Web API → Action controller: routes requests
- Action controller → Host node: sends action goal
- Host node → Device nodes: manages devices
- Device nodes → Equipment drivers: invokes drivers
- Equipment drivers → Device communications: uses interfaces
- System launcher → Device registry: loads device system
- System launcher → Resource tracking: loads resource graph
- Resource visualization → Resource tracking: publishes resource poses
- Operator → Workflow conversion: provides workflow
- Workstation reports → Cloud services: reports completion
- System launcher → Cloud services: requests remote resources