# mywai-ai/i-genius architecture

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

- Interactive diagram: https://gitdiagram.com/mywai-ai/i-genius
- Repository: https://github.com/mywai-ai/i-genius

## Overview

1. **Overall shape**
   - This is a **local-first Streamlit application** for robot demonstration processing.
   - The repository is split into a **presentation layer** (`new_ui` pages/components), a **service layer** that handles uploads and orchestration, and a **processing layer** under `core/` that performs the actual CV/trajectory/DMP work.

2. **Main user entrypoints**
   - The primary app entry is the Streamlit landing page in `src/streamlit_template/new_ui/pages/Common/landing_page.py`.
   - The repo also keeps older/alternate UI and pipeline code under `src/streamlit_template/ui` and `src/streamlit_template/core/*`, which suggests the architecture has evolved from script-like pipelines into a more structured UI/service split.

3. **UI architecture**
   - `new_ui/pages/` contains the route-level screens for the three major workflows: **BAG**, **SVO**, and **Generic**.
   - `new_ui/components/` holds reusable UI widgets such as frame viewers, video players, and stepper bars.
   - `new_ui/Common/` provides shared app state, styling, config, and source definitions.

4. **Service layer boundary**
   - `new_ui/services/` is the orchestration boundary between UI and processing.
   - These services manage uploads, validation, file handling, and pipeline triggers:
     - `zip_upload_handler.py`
     - `frame_service.py`
     - `video_extraction_service.py`
     - `bag_helpers.py`
     - `svo_helpers.py`
     - robot-related services for playback/action
   - This layer is where incoming user data becomes structured runtime artifacts on disk.

5. **Core processing pipelines**
   - The heavy computation lives in `src/streamlit_template/core/`.
   - There are domain-specific workflows:
     - `core/SVO/` for ZED SVO/SVO2-based RGB-D processing
     - `core/BAG/` for ROS bag-style workflows
     - `core/Generic/` for broader inputs such as uploaded video
   - These folders contain ordered step scripts, indicating a **staged pipeline architecture** rather than a single monolithic job.

6. **SVO workflow: the main reusable path**
   - The README makes clear the most mature workflow is **ZED `.svo` / `.svo2` exported into an RGB-D ZIP**.
   - Expected inputs include camera intrinsics, RGB frames, metric depth maps, depth-color previews, and a video preview.
   - The SVO pipeline then runs sequential steps for **hand trajectory extraction, smoothing, object trajectory extraction, grasp estimation, trajectory reconstruction, segmentation, skill extraction, DMP learning/adaptation, and robot playback evaluation**.

7. **BAG workflow**
   - `core/BAG/` mirrors the same high-level progression, but for bag-based demonstration data.
   - It includes explicit numbered stages from frame extraction through DMP learning and skill reuse tests.
   - This suggests BAG is another ingestion path into the same downstream learning and playback concepts, not a separate product line.

8. **Generic / video-oriented workflow**
   - `core/Generic/` provides a less specialized path that supports frame extraction, hand/object detection, trajectory extraction, and DMP generation.
   - The README notes MP4 input is supported in the Skill-Reuse branch, but without metric depth it is less suitable for precise robot-space pick-and-place.
   - Architecturally, this is a **lower-fidelity input path** that converges on the same trajectory/skill outputs.

9. **Shared model and robot asset boundary**
   - `data/Common/` is a shared asset layer rather than runtime output.
   - It contains:
     - AI models for hand and object detection
     - robot descriptions, URDFs, meshes, and config files
   - This boundary is important: processing code depends on these assets, but they are not generated by the app.

10. **Runtime data model**
   - `data/SVO/`, `data/BAG/`, and `data/Generic/` are the local runtime workspaces.
   - Each has subfolders for uploads, downloads, frames, depth, hands, objects, segmentation, plots, videos, and debug artifacts.
   - The architecture is intentionally filesystem-centric: uploads enter the workspace, pipeline steps write intermediate outputs there, and the UI reads them back for visualization.

11. **External integration points**
   - The repo includes `scripts/vulcanexus/`, which is a separate integration surface for **DDS / ROS 2 / Fast DDS** style robot communication.
   - Scripts indicate trajectory publishing/subscribing, edge executors, and WAN transport setup.
   - This is the bridge from local inference/trajectory generation to robot-side execution.

12. **Deployment and runtime**
   - The app runs locally via Streamlit, and there is a Docker path via `docker-compose.yml` and `Dockerfile`.
   - `supervisord.conf` suggests containerized multi-process runtime management.
   - The default local port in the README is 8504; Docker exposes the app on 9002.

13. **Documentation as part of the system**
   - `tutorials/` is not just reference material; it defines the expected pre-processing contract for SVO ZIP creation and custom robot packaging.
   - The tutorials are effectively part of the architecture because they define the data shape that the app’s validators and pipelines expect.

14. **Key architectural takeaway**
   - The repo is a **local, file-backed, stepwise demonstration-processing system**.
   - Data flows from user uploads to structured workspace folders, through domain-specific pipelines, and out to learned trajectories, DMP artifacts, plots, and optional robot execution interfaces.

Main entry points: [`src/streamlit_template/new_ui/pages`](https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/new_ui/pages) (Workflow pages), [`src/streamlit_template/new_ui/services/Common/zip_upload_handler.py`](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Common/zip_upload_handler.py) (Upload handler), [`data/Common`](https://github.com/mywai-ai/i-genius/tree/main/data/Common) (Shared assets), [`src/streamlit_template/new_ui/services/Generic/pipeline_service.py`](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Generic/pipeline_service.py) (Generic service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["UI"]
  node_node_main_app["Main app<br/>entrypoint<br/>[main.py]"]
  node_node_landing_page["Landing page<br/>ui page<br/>[landing_page.py]"]
  node_node_ui_pages["Workflow pages<br/>route screens"]
  node_node_ui_components["UI widgets<br/>shared components"]
  node_node_ui_common["UI common<br/>state and config"]
end

subgraph group_group_services["Services"]
  node_node_upload_handler["Upload handler"]
  node_node_generic_pipeline_service["Generic service<br/>orchestrator"]
  node_node_bag_pipeline_service["BAG service<br/>orchestrator"]
  node_node_svo_pipeline_service["SVO service<br/>orchestrator"]
  node_node_frame_service["Frame service<br/>file service<br/>[frame_service.py]"]
  node_node_video_extraction_service["Video service<br/>media service"]
  node_node_robot_service["Robot service<br/>robot boundary<br/>[robot_service.py]"]
  node_node_robot_action_service["Action service<br/>robot boundary"]
end

subgraph group_group_core["Core pipelines"]
  node_node_generic_core["Generic core<br/>pipeline"]
  node_node_bag_core["BAG core<br/>pipeline"]
  node_node_svo_core["SVO core<br/>pipeline"]
  node_node_common_core["Common core<br/>shared utilities"]
end

subgraph group_group_assets["Assets"]
  node_node_common_data[("Shared assets<br/>models and robot packs")]
  node_node_svo_data[("SVO workspace<br/>runtime workspace")]
  node_node_bag_data[("BAG workspace<br/>runtime workspace")]
  node_node_generic_data[("Generic workspace<br/>runtime workspace")]
end

subgraph group_group_integration["Integration"]
  node_node_vulcanexus_scripts["Vulcanexus scripts<br/>robot integration"]
  node_node_runtime["Docker runtime<br/>deployment"]
  node_node_tutorials["Tutorials<br/>docs contract"]
end

node_node_main_app -->|"opens"| node_node_landing_page
node_node_landing_page -->|"navigates to"| node_node_ui_pages
node_node_ui_pages -->|"uses"| node_node_ui_components
node_node_ui_pages -->|"reads state"| node_node_ui_common
node_node_ui_pages -->|"uploads"| node_node_upload_handler
node_node_ui_pages -->|"runs"| node_node_generic_pipeline_service
node_node_ui_pages -->|"runs"| node_node_bag_pipeline_service
node_node_ui_pages -->|"runs"| node_node_svo_pipeline_service
node_node_upload_handler -->|"stages"| node_node_generic_data
node_node_upload_handler -->|"stages"| node_node_bag_data
node_node_upload_handler -->|"stages"| node_node_svo_data
node_node_generic_pipeline_service -->|"orchestrates"| node_node_generic_core
node_node_bag_pipeline_service -->|"orchestrates"| node_node_bag_core
node_node_svo_pipeline_service -->|"orchestrates"| node_node_svo_core
node_node_generic_pipeline_service -->|"uses"| node_node_frame_service
node_node_generic_pipeline_service -->|"uses"| node_node_video_extraction_service
node_node_svo_pipeline_service -->|"uses"| node_node_common_core
node_node_bag_pipeline_service -->|"uses"| node_node_common_core
node_node_svo_core -->|"depends on"| node_node_common_data
node_node_bag_core -->|"depends on"| node_node_common_data
node_node_generic_core -->|"depends on"| node_node_common_data
node_node_svo_core -->|"reads/writes"| node_node_svo_data
node_node_bag_core -->|"reads/writes"| node_node_bag_data
node_node_generic_core -->|"reads/writes"| node_node_generic_data
node_node_common_core -->|"loads"| node_node_common_data
node_node_robot_service -->|"loads"| node_node_common_data
node_node_robot_action_service -->|"bridges to"| node_node_vulcanexus_scripts
node_node_svo_core -->|"publishes to"| node_node_vulcanexus_scripts
node_node_tutorials -.->|"documents"| node_node_upload_handler
node_node_runtime -->|"runs"| node_node_main_app

click node_node_main_app "https://github.com/mywai-ai/i-genius/blob/main/main.py"
click node_node_landing_page "https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/pages/Common/landing_page.py"
click node_node_ui_pages "https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/new_ui/pages"
click node_node_ui_components "https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/new_ui/components/Common"
click node_node_ui_common "https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/new_ui/Common"
click node_node_upload_handler "https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Common/zip_upload_handler.py"
click node_node_generic_pipeline_service "https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Generic/pipeline_service.py"
click node_node_bag_pipeline_service "https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/BAG/bag_pipeline_service.py"
click node_node_svo_pipeline_service "https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/SVO/svo_pipeline_service.py"
click node_node_frame_service "https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Generic/frame_service.py"
click node_node_video_extraction_service "https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Generic/video_extraction_service.py"
click node_node_robot_service "https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Common/robot_service.py"
click node_node_robot_action_service "https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Common/robot_action_service.py"
click node_node_generic_core "https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/core/Generic"
click node_node_bag_core "https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/core/BAG"
click node_node_svo_core "https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/core/SVO"
click node_node_common_core "https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/core/Common"
click node_node_common_data "https://github.com/mywai-ai/i-genius/tree/main/data/Common"
click node_node_svo_data "https://github.com/mywai-ai/i-genius/tree/main/data/SVO"
click node_node_bag_data "https://github.com/mywai-ai/i-genius/tree/main/data/BAG"
click node_node_generic_data "https://github.com/mywai-ai/i-genius/tree/main/data/Generic"
click node_node_vulcanexus_scripts "https://github.com/mywai-ai/i-genius/tree/main/scripts/vulcanexus"
click node_node_runtime "https://github.com/mywai-ai/i-genius/tree/main/Dockerfile"
click node_node_tutorials "https://github.com/mywai-ai/i-genius/tree/main/tutorials"

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_node_main_app,node_node_landing_page,node_node_ui_pages,node_node_ui_components,node_node_ui_common toneBlue
class node_node_upload_handler,node_node_generic_pipeline_service,node_node_bag_pipeline_service,node_node_svo_pipeline_service,node_node_frame_service,node_node_video_extraction_service,node_node_robot_service,node_node_robot_action_service toneAmber
class node_node_generic_core,node_node_bag_core,node_node_svo_core,node_node_common_core toneMint
class node_node_common_data,node_node_svo_data,node_node_bag_data,node_node_generic_data toneRose
class node_node_vulcanexus_scripts,node_node_runtime,node_node_tutorials toneIndigo
```

## Components

### UI

Streamlit screens, shared widgets, and app state

- [Main app](https://github.com/mywai-ai/i-genius/blob/main/main.py): entrypoint · Streamlit application entrypoint · `main.py`
- [Landing page](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/pages/Common/landing_page.py): ui page · Primary Streamlit entry screen · `src/streamlit_template/new_ui/pages/Common/landing_page.py`
- [Workflow pages](https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/new_ui/pages): route screens · BAG, SVO, and Generic workflow screens · `src/streamlit_template/new_ui/pages`
- [UI widgets](https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/new_ui/components/Common): shared components · Frame viewer, video player, and stepper UI · `src/streamlit_template/new_ui/components/Common`
- [UI common](https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/new_ui/Common): state and config · Shared app state, styling, utilities, and sources · `src/streamlit_template/new_ui/Common`

### Services

Orchestration boundary between UI and processing

- [Upload handler](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Common/zip_upload_handler.py): service · Validates and stages incoming files · `src/streamlit_template/new_ui/services/Common/zip_upload_handler.py`
- [Generic service](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Generic/pipeline_service.py): orchestrator · Coordinates the generic workflow · `src/streamlit_template/new_ui/services/Generic/pipeline_service.py`
- [BAG service](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/BAG/bag_pipeline_service.py): orchestrator · Coordinates the BAG workflow · `src/streamlit_template/new_ui/services/BAG/bag_pipeline_service.py`
- [SVO service](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/SVO/svo_pipeline_service.py): orchestrator · Coordinates the SVO workflow · `src/streamlit_template/new_ui/services/SVO/svo_pipeline_service.py`
- [Frame service](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Generic/frame_service.py): file service · Frame extraction and workspace handling · `src/streamlit_template/new_ui/services/Generic/frame_service.py`
- [Video service](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Generic/video_extraction_service.py): media service · Extracts or builds videos for preview and processing · `src/streamlit_template/new_ui/services/Generic/video_extraction_service.py`
- [Robot service](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Common/robot_service.py): robot boundary · Robot model and execution support · `src/streamlit_template/new_ui/services/Common/robot_service.py`
- [Action service](https://github.com/mywai-ai/i-genius/blob/main/src/streamlit_template/new_ui/services/Common/robot_action_service.py): robot boundary · Robot playback and action triggering · `src/streamlit_template/new_ui/services/Common/robot_action_service.py`

### Core pipelines

Domain workflows that perform extraction, learning, and replay

- [Generic core](https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/core/Generic): pipeline · Lower-fidelity video-oriented processing path · `src/streamlit_template/core/Generic`
- [BAG core](https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/core/BAG): pipeline · Bag-based demonstration processing path · `src/streamlit_template/core/BAG`
- [SVO core](https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/core/SVO): pipeline · Main RGB-D SVO demonstration processing path · `src/streamlit_template/core/SVO`
- [Common core](https://github.com/mywai-ai/i-genius/tree/main/src/streamlit_template/core/Common): shared utilities · Shared config, cleanup, depth estimation, and playback helpers · `src/streamlit_template/core/Common`

### Assets

Shared models, robot packages, and filesystem workspaces

- [Shared assets](https://github.com/mywai-ai/i-genius/tree/main/data/Common): models and robot packs · Reusable AI models and robot descriptions · `data/Common`
- [SVO workspace](https://github.com/mywai-ai/i-genius/tree/main/data/SVO): runtime workspace · Filesystem-backed SVO uploads, intermediates, and outputs · `data/SVO`
- [BAG workspace](https://github.com/mywai-ai/i-genius/tree/main/data/BAG): runtime workspace · Filesystem-backed BAG uploads, intermediates, and outputs · `data/BAG`
- [Generic workspace](https://github.com/mywai-ai/i-genius/tree/main/data/Generic): runtime workspace · Filesystem-backed generic uploads, intermediates, and outputs · `data/Generic`

### Integration

Robot communication and container/runtime entrypoints

- [Vulcanexus scripts](https://github.com/mywai-ai/i-genius/tree/main/scripts/vulcanexus): robot integration · DDS/ROS2/Fast DDS publishing, subscribing, and edge execution scripts · `scripts/vulcanexus`
- [Docker runtime](https://github.com/mywai-ai/i-genius/tree/main/Dockerfile): deployment · Container and process supervision for local execution · `Dockerfile`
- [Tutorials](https://github.com/mywai-ai/i-genius/tree/main/tutorials): docs contract · Input packaging and preprocessing contracts for workflows · `tutorials`

## Connections

- Main app → Landing page: opens · Main entry loads the landing page
- Landing page → Workflow pages: navigates to · Landing page routes into workflow screens
- Workflow pages → UI widgets: uses · Workflow pages compose shared widgets
- Workflow pages → UI common: reads state · Pages rely on shared app state and config
- Workflow pages → Upload handler: uploads · Pages hand user files to the upload boundary
- Workflow pages → Generic service: runs · Generic UI triggers generic orchestration
- Workflow pages → BAG service: runs · BAG UI triggers BAG orchestration
- Workflow pages → SVO service: runs · SVO UI triggers SVO orchestration
- Upload handler → Generic workspace: stages · Uploaded generic inputs are written to workspace folders
- Upload handler → BAG workspace: stages · Uploaded bag inputs are written to workspace folders
- Upload handler → SVO workspace: stages · Uploaded SVO inputs are written to workspace folders
- Generic service → Generic core: orchestrates · Generic service invokes the core pipeline scripts
- BAG service → BAG core: orchestrates · BAG service invokes the BAG pipeline scripts
- SVO service → SVO core: orchestrates · SVO service invokes the SVO pipeline scripts
- Generic service → Frame service: uses · Generic orchestration depends on frame extraction
- Generic service → Video service: uses · Generic orchestration depends on video preparation
- SVO service → Common core: uses · SVO workflow shares depth estimation and playback helpers
- BAG service → Common core: uses · BAG workflow shares depth estimation and playback helpers
- SVO core → Shared assets: depends on · SVO pipeline consumes shared models and robot assets
- BAG core → Shared assets: depends on · BAG pipeline consumes shared models and robot assets
- Generic core → Shared assets: depends on · Generic pipeline consumes shared models and robot assets
- SVO core → SVO workspace: reads/writes · SVO steps materialize frames, depth, plots, and outputs
- BAG core → BAG workspace: reads/writes · BAG steps materialize frames, plots, DMPs, and outputs
- Generic core → Generic workspace: reads/writes · Generic steps materialize extracted frames, detections, and DMPs
- Common core → Shared assets: loads · Shared core helpers use AI models and robot descriptions
- Robot service → Shared assets: loads · Robot service uses robot packages and meshes
- Action service → Vulcanexus scripts: bridges to · Robot action support connects to DDS/ROS2 tooling
- SVO core → Vulcanexus scripts: publishes to · SVO playback and evaluation can feed robot execution
- Tutorials → Upload handler: documents · Tutorials define the expected upload and packaging contract
- Docker runtime → Main app: runs · Container runtime launches the Streamlit application