# stephen4513/interactive-lab-hub architecture

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

- Interactive diagram: https://gitdiagram.com/stephen4513/interactive-lab-hub
- Repository: https://github.com/stephen4513/interactive-lab-hub

## Overview

This repository is a collection of Interactive Device Design lab prototypes, not one integrated application. Its workflows range from Raspberry Pi hardware interactions and speech interfaces to camera-based observation and networked pixel/device interactions. The clearest internal call paths are the study assistant’s reuse of speech output, hand-pose tracking, the pixel server’s optional MQTT bridge, and the MQTT rule exercises. Many other lab scripts are listed but unsampled, so their connections are omitted rather than inferred.

Main entry points: [`Lab 6/stretch/common.py`](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/stretch/common.py) (MQTT Shared Client), [`Lab 6/mqtt_bridge.py`](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/mqtt_bridge.py) (Pixel MQTT Bridge), [`Lab 6/app.py`](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/app.py) (Collaborative Pixel Server), [`Lab 3/speech-scripts/echo_bot.py`](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%203/speech-scripts/echo_bot.py) (Echo Voice Loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Hardware Prototypes"]
  node_lab2_clock["Clock Prototypes"]
  node_lab2_display["Display and Sensors"]
  node_lab4_controls["Physical Controls"]
end

subgraph group_speech["Speech Interfaces"]
  node_echo["Echo Voice Loop<br/>[echo_bot.py]"]
  node_study["Study Assistant<br/>[study_assistant.py]"]
  node_speech_tools["Speech Experiments"]
end

subgraph group_vision["Observant Systems"]
  node_hand_tracking["Hand Tracking"]
  node_hand_pose["Gesture Volume Control<br/>[hand_pose.py]"]
  node_yolo_pipeline["Camera-to-Qwen Pipeline<br/>[yolo_to_qwen.py]"]
  node_vision_apps["Vision Prototypes"]
end

subgraph group_network["Networked Interactions"]
  node_pixel_server["Collaborative Pixel Server<br/>[app.py]"]
  node_mqtt_bridge["Pixel MQTT Bridge<br/>[mqtt_bridge.py]"]
  node_mqtt_viewer["MQTT Viewer<br/>[mqtt_viewer.py]"]
  node_pixel_publisher["Pixel Publisher"]
  node_descriptions["Device Descriptions<br/>[describe.py]"]
  node_rule_compiler["Rule Compiler<br/>[compile_rule.py]"]
  node_rule_runner["MQTT Rule Runner<br/>[run_rule.py]"]
  node_mqtt_common["MQTT Shared Client<br/>[common.py]"]
end

node_user(("Device User"))
node_camera(("Camera"))
node_ollama(("Ollama Service"))
node_mqtt_broker(("MQTT Broker"))
node_web_clients(("WebSocket Clients"))
node_audio_devices(("Audio Devices"))

node_study -->|"uses speaker"| node_echo
node_user -->|"speaks to"| node_echo
node_echo -->|"records and plays"| node_audio_devices
node_user -->|"operates"| node_study
node_hand_pose -->|"uses landmarks"| node_hand_tracking
node_camera -->|"provides frames"| node_yolo_pipeline
node_yolo_pipeline -->|"requests answer"| node_ollama
node_pixel_server -->|"serves updates"| node_web_clients
node_pixel_server -.->|"starts optionally"| node_mqtt_bridge
node_mqtt_bridge -->|"subscribes"| node_mqtt_broker
node_mqtt_bridge -->|"broadcasts updates"| node_pixel_server
node_descriptions -->|"connects through"| node_mqtt_common
node_rule_compiler -->|"reads descriptions"| node_mqtt_common
node_rule_runner -->|"connects through"| node_mqtt_common
node_mqtt_common -->|"connects"| node_mqtt_broker
node_rule_runner -->|"subscribes and publishes"| node_mqtt_broker

click node_lab2_clock "https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%202"
click node_lab2_display "https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%202"
click node_lab4_controls "https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%204"
click node_echo "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%203/speech-scripts/echo_bot.py"
click node_study "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%203/speech-scripts/study_assistant.py"
click node_speech_tools "https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%203/speech-scripts"
click node_hand_tracking "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%205/HandTrackingModule.py"
click node_hand_pose "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%205/hand_pose.py"
click node_yolo_pipeline "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%205/yolo_to_qwen.py"
click node_vision_apps "https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%205"
click node_pixel_server "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/app.py"
click node_mqtt_bridge "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/mqtt_bridge.py"
click node_mqtt_viewer "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/mqtt_viewer.py"
click node_pixel_publisher "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/pixel_grid_publisher.py"
click node_descriptions "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/stretch/describe.py"
click node_rule_compiler "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/stretch/compile_rule.py"
click node_rule_runner "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/stretch/run_rule.py"
click node_mqtt_common "https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/stretch/common.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_lab2_clock,node_lab2_display,node_lab4_controls,node_user,node_web_clients toneBlue
class node_echo,node_study,node_speech_tools toneAmber
class node_hand_tracking,node_hand_pose,node_yolo_pipeline,node_vision_apps toneMint
class node_pixel_server,node_mqtt_bridge,node_mqtt_viewer,node_pixel_publisher,node_descriptions,node_rule_compiler,node_rule_runner,node_mqtt_common toneRose
class node_camera,node_ollama,node_mqtt_broker,node_audio_devices toneIndigo
```

## Components

### Hardware Prototypes

- [Clock Prototypes](https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%202): `Lab 2`
- [Display and Sensors](https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%202): `Lab 2`
- [Physical Controls](https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%204): `Lab 4`

### Speech Interfaces

- [Echo Voice Loop](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%203/speech-scripts/echo_bot.py): `Lab 3/speech-scripts/echo_bot.py`
- [Study Assistant](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%203/speech-scripts/study_assistant.py): `Lab 3/speech-scripts/study_assistant.py`
- [Speech Experiments](https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%203/speech-scripts): `Lab 3/speech-scripts`

### Observant Systems

- [Hand Tracking](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%205/HandTrackingModule.py): `Lab 5/HandTrackingModule.py`
- [Gesture Volume Control](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%205/hand_pose.py): `Lab 5/hand_pose.py`
- [Camera-to-Qwen Pipeline](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%205/yolo_to_qwen.py): `Lab 5/yolo_to_qwen.py`
- [Vision Prototypes](https://github.com/stephen4513/interactive-lab-hub/tree/Fall2026/Lab%205): `Lab 5`

### Networked Interactions

- [Collaborative Pixel Server](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/app.py): `Lab 6/app.py`
- [Pixel MQTT Bridge](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/mqtt_bridge.py): `Lab 6/mqtt_bridge.py`
- [MQTT Viewer](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/mqtt_viewer.py): `Lab 6/mqtt_viewer.py`
- [Pixel Publisher](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/pixel_grid_publisher.py): `Lab 6/pixel_grid_publisher.py`
- [Device Descriptions](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/stretch/describe.py): `Lab 6/stretch/describe.py`
- [Rule Compiler](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/stretch/compile_rule.py): `Lab 6/stretch/compile_rule.py`
- [MQTT Rule Runner](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/stretch/run_rule.py): `Lab 6/stretch/run_rule.py`
- [MQTT Shared Client](https://github.com/stephen4513/interactive-lab-hub/blob/Fall2026/Lab%206/stretch/common.py): `Lab 6/stretch/common.py`

### Other components

- **Device User**
- **Camera**
- **Ollama Service**
- **MQTT Broker**
- **WebSocket Clients**
- **Audio Devices**

## Connections

- Study Assistant → Echo Voice Loop: uses speaker (evidence: `Lab 3/speech-scripts/study_assistant.py`)
- Device User → Echo Voice Loop: speaks to (evidence: `Lab 3/speech-scripts/echo_bot.py`)
- Echo Voice Loop → Audio Devices: records and plays (evidence: `Lab 3/speech-scripts/echo_bot.py`)
- Device User → Study Assistant: operates (evidence: `Lab 3/speech-scripts/study_assistant.py`)
- Gesture Volume Control → Hand Tracking: uses landmarks (evidence: `Lab 5/hand_pose.py`)
- Camera → Camera-to-Qwen Pipeline: provides frames (evidence: `Lab 5/yolo_to_qwen.py`)
- Camera-to-Qwen Pipeline → Ollama Service: requests answer (evidence: `Lab 5/yolo_to_qwen.py`)
- Collaborative Pixel Server → WebSocket Clients: serves updates (evidence: `Lab 6/app.py`)
- Collaborative Pixel Server → Pixel MQTT Bridge: starts optionally (evidence: `Lab 6/app.py`)
- Pixel MQTT Bridge → MQTT Broker: subscribes (evidence: `Lab 6/mqtt_bridge.py`)
- Pixel MQTT Bridge → Collaborative Pixel Server: broadcasts updates (evidence: `Lab 6/mqtt_bridge.py`)
- Device Descriptions → MQTT Shared Client: connects through (evidence: `Lab 6/stretch/describe.py`)
- Rule Compiler → MQTT Shared Client: reads descriptions (evidence: `Lab 6/stretch/compile_rule.py`)
- MQTT Rule Runner → MQTT Shared Client: connects through (evidence: `Lab 6/stretch/run_rule.py`)
- MQTT Shared Client → MQTT Broker: connects (evidence: `Lab 6/stretch/common.py`)
- MQTT Rule Runner → MQTT Broker: subscribes and publishes (evidence: `Lab 6/stretch/run_rule.py`)
