# iunacy/viper architecture

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

- Interactive diagram: https://gitdiagram.com/iunacy/viper
- Repository: https://github.com/iunacy/viper

## Overview

VIPER is a robotics research and demonstration system for bounded, feedback-driven manipulation across robot arms. Its user-facing workflow is to run or inspect pick-and-place trials, qualify or collect recorded evidence, prepare datasets for learning experiments, and review outcomes through replay and comparison interfaces. The repository also contains a classical motion-planning and simulation runtime, an adaptive-control research branch, and a browser laboratory for recorded scenarios. Edges are limited to relationships shown in the README or the supplied source excerpts and index; several substantial subsystems are represented by their exact directory paths because their internal wiring was not sampled.

Main entry points: [`embodiment/qualify.py`](https://github.com/iunacy/viper/blob/main/embodiment/qualify.py) (Trial qualification), [`embodiment/dataset.py`](https://github.com/iunacy/viper/blob/main/embodiment/dataset.py) (Dataset validation), [`adaptive/pipeline.py`](https://github.com/iunacy/viper/blob/main/adaptive/pipeline.py) (Experiment pipeline), [`web/src/App.tsx`](https://github.com/iunacy/viper/blob/main/web/src/App.tsx) (Browser laboratory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_robotics["Robot execution"]
  node_qualification["Trial qualification<br/>[qualify.py]"]
  node_assets["Robot assets<br/>[assets.py]"]
  node_panda["Panda adapter<br/>[panda.py]"]
end

subgraph group_evidence["Trials and evidence"]
  node_collection["Trial collection<br/>[collection.py]"]
  node_dataset["Dataset validation<br/>[dataset.py]"]
  node_recording["Trial recording<br/>[recording.py]"]
  node_replay["Episode replay<br/>[replay.py]"]
end

subgraph group_learning["Adaptive learning"]
  node_adaptive_learning["Adaptive learning<br/>[learning.py]"]
  node_adaptive_pipeline["Experiment pipeline<br/>[pipeline.py]"]
  node_revision_learning["Revision experiments"]
  node_revision["Revision analysis<br/>[revision.py]"]
end

subgraph group_motion["Motion runtime"]
  node_simulation["MuJoCo simulation<br/>[simulation.hpp]"]
  node_motion_planning["Motion planning<br/>[motion.cpp]"]
end

subgraph group_interfaces["Research interfaces"]
  node_interactive_app["Interactive service<br/>[app.py]"]
  node_interactive_engine["Execution comparison<br/>[engine.py]"]
  node_browser_lab["Browser laboratory<br/>[App.tsx]"]
  node_research_view["Research view<br/>[Research.tsx]"]
  node_recorded_scenarios["Recorded scenarios<br/>[replay.ts]"]
end

node_user(("Research user"))

node_user -->|"runs trials"| node_qualification
node_qualification -->|"validates assets"| node_assets
node_qualification -->|"checks embodiment"| node_panda
node_qualification -->|"records outcomes"| node_recording
node_collection -->|"prepares episodes"| node_dataset
node_dataset -->|"validates telemetry"| node_recording
node_dataset -->|"checks assets"| node_assets
node_dataset -->|"checks joints"| node_panda
node_replay -->|"loads trials"| node_recording
node_user -->|"runs experiments"| node_adaptive_pipeline
node_adaptive_pipeline -->|"uses learner"| node_adaptive_learning
node_revision_learning -->|"uses learner"| node_adaptive_learning
node_revision_learning -->|"evaluates episodes"| node_adaptive_pipeline
node_revision -->|"analyzes results"| node_adaptive_learning
node_revision -->|"analyzes runs"| node_adaptive_pipeline
node_motion_planning -->|"plans and executes"| node_simulation
node_user -.->|"requests execution"| node_interactive_app
node_interactive_app -->|"runs comparison"| node_interactive_engine
node_interactive_engine -.->|"renders execution"| node_simulation
node_user -->|"opens laboratory"| node_browser_lab
node_browser_lab -->|"loads recordings"| node_recorded_scenarios
node_browser_lab -->|"shows research"| node_research_view
node_research_view -->|"loads replay data"| node_replay

click node_qualification "https://github.com/iunacy/viper/blob/main/embodiment/qualify.py"
click node_assets "https://github.com/iunacy/viper/blob/main/embodiment/assets.py"
click node_panda "https://github.com/iunacy/viper/blob/main/embodiment/panda.py"
click node_collection "https://github.com/iunacy/viper/blob/main/embodiment/collection.py"
click node_dataset "https://github.com/iunacy/viper/blob/main/embodiment/dataset.py"
click node_recording "https://github.com/iunacy/viper/blob/main/embodiment/recording.py"
click node_replay "https://github.com/iunacy/viper/blob/main/embodiment/replay.py"
click node_adaptive_learning "https://github.com/iunacy/viper/blob/main/adaptive/learning.py"
click node_adaptive_pipeline "https://github.com/iunacy/viper/blob/main/adaptive/pipeline.py"
click node_revision_learning "https://github.com/iunacy/viper/blob/main/adaptive/revision_learning.py"
click node_revision "https://github.com/iunacy/viper/blob/main/adaptive/revision.py"
click node_simulation "https://github.com/iunacy/viper/blob/main/include/relic/simulation.hpp"
click node_motion_planning "https://github.com/iunacy/viper/blob/main/src/motion.cpp"
click node_interactive_app "https://github.com/iunacy/viper/blob/main/interactive/app.py"
click node_interactive_engine "https://github.com/iunacy/viper/blob/main/interactive/engine.py"
click node_browser_lab "https://github.com/iunacy/viper/blob/main/web/src/App.tsx"
click node_research_view "https://github.com/iunacy/viper/blob/main/web/src/Research.tsx"
click node_recorded_scenarios "https://github.com/iunacy/viper/blob/main/web/src/replay.ts"

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_qualification,node_assets,node_panda,node_user toneBlue
class node_collection,node_dataset,node_recording,node_replay toneAmber
class node_adaptive_learning,node_adaptive_pipeline,node_revision_learning,node_revision toneMint
class node_simulation,node_motion_planning toneRose
class node_interactive_app,node_interactive_engine,node_browser_lab,node_research_view,node_recorded_scenarios toneIndigo
```

## Components

### Robot execution

- [Trial qualification](https://github.com/iunacy/viper/blob/main/embodiment/qualify.py): `embodiment/qualify.py`
- [Robot assets](https://github.com/iunacy/viper/blob/main/embodiment/assets.py): `embodiment/assets.py`
- [Panda adapter](https://github.com/iunacy/viper/blob/main/embodiment/panda.py): `embodiment/panda.py`

### Trials and evidence

- [Trial collection](https://github.com/iunacy/viper/blob/main/embodiment/collection.py): `embodiment/collection.py`
- [Dataset validation](https://github.com/iunacy/viper/blob/main/embodiment/dataset.py): `embodiment/dataset.py`
- [Trial recording](https://github.com/iunacy/viper/blob/main/embodiment/recording.py): `embodiment/recording.py`
- [Episode replay](https://github.com/iunacy/viper/blob/main/embodiment/replay.py): `embodiment/replay.py`

### Adaptive learning

- [Adaptive learning](https://github.com/iunacy/viper/blob/main/adaptive/learning.py): `adaptive/learning.py`
- [Experiment pipeline](https://github.com/iunacy/viper/blob/main/adaptive/pipeline.py): `adaptive/pipeline.py`
- [Revision experiments](https://github.com/iunacy/viper/blob/main/adaptive/revision_learning.py): `adaptive/revision_learning.py`
- [Revision analysis](https://github.com/iunacy/viper/blob/main/adaptive/revision.py): `adaptive/revision.py`

### Motion runtime

- [MuJoCo simulation](https://github.com/iunacy/viper/blob/main/include/relic/simulation.hpp): `include/relic/simulation.hpp`
- [Motion planning](https://github.com/iunacy/viper/blob/main/src/motion.cpp): `src/motion.cpp`

### Research interfaces

- [Interactive service](https://github.com/iunacy/viper/blob/main/interactive/app.py): `interactive/app.py`
- [Execution comparison](https://github.com/iunacy/viper/blob/main/interactive/engine.py): `interactive/engine.py`
- [Browser laboratory](https://github.com/iunacy/viper/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Research view](https://github.com/iunacy/viper/blob/main/web/src/Research.tsx): `web/src/Research.tsx`
- [Recorded scenarios](https://github.com/iunacy/viper/blob/main/web/src/replay.ts): `web/src/replay.ts`

### Other components

- **Research user**

## Connections

- Research user → Trial qualification: runs trials (evidence: `README.md`)
- Trial qualification → Robot assets: validates assets (evidence: `embodiment/qualify.py`)
- Trial qualification → Panda adapter: checks embodiment (evidence: `embodiment/qualify.py`)
- Trial qualification → Trial recording: records outcomes (evidence: `embodiment/qualify.py`)
- Trial collection → Dataset validation: prepares episodes (evidence: `embodiment/collection.py`)
- Dataset validation → Trial recording: validates telemetry (evidence: `embodiment/dataset.py`)
- Dataset validation → Robot assets: checks assets (evidence: `embodiment/dataset.py`)
- Dataset validation → Panda adapter: checks joints (evidence: `embodiment/dataset.py`)
- Episode replay → Trial recording: loads trials (evidence: `embodiment/replay.py`)
- Research user → Experiment pipeline: runs experiments (evidence: `README.md`)
- Experiment pipeline → Adaptive learning: uses learner (evidence: `adaptive/learning.py`)
- Revision experiments → Adaptive learning: uses learner (evidence: `adaptive/revision_learning.py`)
- Revision experiments → Experiment pipeline: evaluates episodes (evidence: `adaptive/revision_learning.py`)
- Revision analysis → Adaptive learning: analyzes results (evidence: `adaptive/revision.py`)
- Revision analysis → Experiment pipeline: analyzes runs (evidence: `adaptive/revision.py`)
- Motion planning → MuJoCo simulation: plans and executes (evidence: `src/motion.cpp`)
- Research user → Interactive service: requests execution (evidence: `interactive/app.py`)
- Interactive service → Execution comparison: runs comparison (evidence: `interactive/app.py`)
- Execution comparison → MuJoCo simulation: renders execution
- Research user → Browser laboratory: opens laboratory (evidence: `README.md`)
- Browser laboratory → Recorded scenarios: loads recordings (evidence: `web/src/App.tsx`)
- Browser laboratory → Research view: shows research (evidence: `web/src/App.tsx`)
- Research view → Episode replay: loads replay data