# couchpugtato/vortex architecture

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

- Interactive diagram: https://gitdiagram.com/couchpugtato/vortex
- Repository: https://github.com/couchpugtato/vortex

## Overview

Vortex’s main workflow captures camera images, detects AprilTags, estimates camera and robot pose from camera settings and the field layout, then publishes detections and localization for robot consumers. Its other substantial product branches are interactive simulation and failure replay, synthetic-image regression, camera calibration, Jetson acceleration, and deployment. Edges are limited to relationships shown in the excerpts, SOURCE INDEX references, or README; unsampled subsystem internals and some runtime wiring are therefore not expanded.

Main entry points: [`src/main.rs`](https://github.com/couchpugtato/vortex/blob/main/src/main.rs) (Vision pipeline), [`chassis_sim/drive.py`](https://github.com/couchpugtato/vortex/blob/main/chassis_sim/drive.py) (Interactive simulator), [`src/detector.rs`](https://github.com/couchpugtato/vortex/blob/main/src/detector.rs) (AprilTag detection), [`deployment/src/main.rs`](https://github.com/couchpugtato/vortex/blob/main/deployment/src/main.rs) (Native deployment controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vision["Vision runtime"]
  node_vision_app["Vision pipeline<br/>[main.rs]"]
  node_config["Camera and field config<br/>[config.rs]"]
  node_preprocess["Image preprocessing<br/>[preprocess.rs]"]
  node_detector["AprilTag detection<br/>[detector.rs]"]
  node_refinement["Tag refinement<br/>[tag_refine.rs]"]
  node_pose["Pose estimation<br/>[pose.rs]"]
  node_gpu["GPU detection<br/>[gpu_detector.rs]"]
  node_vpi["VPI acceleration<br/>[vpi.rs]"]
  node_yolo["TensorRT objects<br/>[yolo_detector.rs]"]
  node_health["Runtime health<br/>[runtime_health.rs]"]
  node_diagnostics["Runtime diagnostics"]
end

subgraph group_deploy["Deployment"]
  node_deployment_ui["Deployment desktop app<br/>[main.js]"]
  node_renderer["Deployment interface<br/>[app.js]"]
  node_staging["Release staging<br/>[staging-deploy.js]"]
  node_deployment_controller["Native deployment controller<br/>[main.rs]"]
  node_activation["Release activation<br/>[activation.rs]"]
  node_service["Service management<br/>[service.rs]"]
end

subgraph group_simulation["Simulation and validation"]
  node_simulator["Interactive simulator<br/>[drive.py]"]
  node_routes["Chassis routes<br/>[routes.py]"]
  node_ghost["Ghost prediction"]
  node_terrain["Field terrain<br/>[terrain.py]"]
  node_failure["Failure capture and replay<br/>[failure_capture.py]"]
  node_test_generation["Synthetic image generation<br/>[generate.py]"]
  node_test_replay["Native regression replay<br/>[main.rs]"]
  node_test_runner["Regression runner<br/>[run.py]"]
end

subgraph group_tools["Calibration and acceleration"]
  node_intrinsics["Intrinsics calibration"]
  node_distortion["Distortion calibration"]
  node_tag_calibration["AprilTag calibration detection"]
  node_engine_builder["TensorRT engine builder<br/>[build_engine.cpp]"]
end

node_operator(("Operator"))
node_camera(("Camera input"))
node_robot(("Robot consumer"))

node_camera -->|"supplies frames"| node_vision_app
node_vision_app -->|"loads settings"| node_config
node_vision_app -->|"uses"| node_preprocess
node_vision_app -->|"dispatches detection"| node_detector
node_detector -->|"builds patches"| node_refinement
node_detector -->|"estimates tag pose"| node_pose
node_vision_app -->|"estimates robot pose"| node_pose
node_vision_app -->|"uses optional backend"| node_gpu
node_vision_app -->|"uses optional acceleration"| node_vpi
node_vision_app -->|"dispatches object detection"| node_yolo
node_vision_app -->|"reports health"| node_health
node_vision_app -->|"collects diagnostics"| node_diagnostics
node_vision_app -->|"publishes telemetry"| node_robot
node_operator -->|"configures deployment"| node_deployment_ui
node_renderer -.->|"uses desktop services"| node_deployment_ui
node_deployment_ui -->|"stages release"| node_staging
node_staging -->|"uploads and invokes"| node_deployment_controller
node_deployment_controller -.->|"activates release"| node_activation
node_deployment_controller -->|"manages service"| node_service
node_operator -->|"drives simulation"| node_simulator
node_simulator -->|"loads route behavior"| node_routes
node_simulator -->|"uses prediction"| node_ghost
node_simulator -->|"uses field terrain"| node_terrain
node_routes -->|"reads bumps"| node_terrain
node_routes -->|"uses motion step"| node_simulator
node_simulator -->|"captures failures"| node_failure
node_simulator -->|"replays frames"| node_test_replay
node_test_runner -->|"generates scenarios"| node_test_generation
node_test_runner -->|"runs native replay"| node_test_replay
node_operator -->|"calibrates camera"| node_intrinsics
node_operator -->|"calibrates distortion"| node_distortion
node_tag_calibration -.->|"provides tag observations"| node_intrinsics
node_engine_builder -->|"builds inference engine"| node_yolo

click node_vision_app "https://github.com/couchpugtato/vortex/blob/main/src/main.rs"
click node_config "https://github.com/couchpugtato/vortex/blob/main/src/config.rs"
click node_preprocess "https://github.com/couchpugtato/vortex/blob/main/src/preprocess.rs"
click node_detector "https://github.com/couchpugtato/vortex/blob/main/src/detector.rs"
click node_refinement "https://github.com/couchpugtato/vortex/blob/main/src/tag_refine.rs"
click node_pose "https://github.com/couchpugtato/vortex/blob/main/src/pose.rs"
click node_gpu "https://github.com/couchpugtato/vortex/blob/main/src/gpu_detector.rs"
click node_vpi "https://github.com/couchpugtato/vortex/blob/main/src/vpi.rs"
click node_yolo "https://github.com/couchpugtato/vortex/blob/main/src/yolo_detector.rs"
click node_health "https://github.com/couchpugtato/vortex/blob/main/src/runtime_health.rs"
click node_diagnostics "https://github.com/couchpugtato/vortex/blob/main/src/runtime_diagnostics.rs"
click node_deployment_ui "https://github.com/couchpugtato/vortex/blob/main/VortexDeploymentInterface/main.js"
click node_renderer "https://github.com/couchpugtato/vortex/blob/main/VortexDeploymentInterface/renderer/app.js"
click node_staging "https://github.com/couchpugtato/vortex/blob/main/VortexDeploymentInterface/staging-deploy.js"
click node_deployment_controller "https://github.com/couchpugtato/vortex/blob/main/deployment/src/main.rs"
click node_activation "https://github.com/couchpugtato/vortex/blob/main/deployment/src/activation.rs"
click node_service "https://github.com/couchpugtato/vortex/blob/main/deployment/src/service.rs"
click node_simulator "https://github.com/couchpugtato/vortex/blob/main/chassis_sim/drive.py"
click node_routes "https://github.com/couchpugtato/vortex/blob/main/chassis_sim/routes.py"
click node_ghost "https://github.com/couchpugtato/vortex/blob/main/chassis_sim/ghost_prediction.py"
click node_terrain "https://github.com/couchpugtato/vortex/blob/main/chassis_sim/terrain.py"
click node_failure "https://github.com/couchpugtato/vortex/blob/main/chassis_sim/failure_capture.py"
click node_test_generation "https://github.com/couchpugtato/vortex/blob/main/simulation_tests/generate.py"
click node_test_replay "https://github.com/couchpugtato/vortex/blob/main/simulation_tests/replay/src/main.rs"
click node_test_runner "https://github.com/couchpugtato/vortex/blob/main/simulation_tests/run.py"
click node_intrinsics "https://github.com/couchpugtato/vortex/blob/main/camera_calibration/camera_intrinsics_solver.py"
click node_distortion "https://github.com/couchpugtato/vortex/blob/main/camera_calibration/camera_distortion_solver.py"
click node_tag_calibration "https://github.com/couchpugtato/vortex/blob/main/camera_calibration/detect_apriltags.py"
click node_engine_builder "https://github.com/couchpugtato/vortex/blob/main/model_builder/build_engine.cpp"

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_vision_app,node_config,node_preprocess,node_detector,node_refinement,node_pose,node_gpu,node_vpi,node_yolo,node_health,node_diagnostics toneBlue
class node_deployment_ui,node_renderer,node_staging,node_deployment_controller,node_activation,node_service toneAmber
class node_simulator,node_routes,node_ghost,node_terrain,node_failure,node_test_generation,node_test_replay,node_test_runner toneMint
class node_intrinsics,node_distortion,node_tag_calibration,node_engine_builder toneRose
class node_operator,node_camera,node_robot toneIndigo
```

## Components

### Vision runtime

- [Vision pipeline](https://github.com/couchpugtato/vortex/blob/main/src/main.rs): `src/main.rs`
- [Camera and field config](https://github.com/couchpugtato/vortex/blob/main/src/config.rs): `src/config.rs`
- [Image preprocessing](https://github.com/couchpugtato/vortex/blob/main/src/preprocess.rs): `src/preprocess.rs`
- [AprilTag detection](https://github.com/couchpugtato/vortex/blob/main/src/detector.rs): `src/detector.rs`
- [Tag refinement](https://github.com/couchpugtato/vortex/blob/main/src/tag_refine.rs): `src/tag_refine.rs`
- [Pose estimation](https://github.com/couchpugtato/vortex/blob/main/src/pose.rs): `src/pose.rs`
- [GPU detection](https://github.com/couchpugtato/vortex/blob/main/src/gpu_detector.rs): `src/gpu_detector.rs`
- [VPI acceleration](https://github.com/couchpugtato/vortex/blob/main/src/vpi.rs): `src/vpi.rs`
- [TensorRT objects](https://github.com/couchpugtato/vortex/blob/main/src/yolo_detector.rs): `src/yolo_detector.rs`
- [Runtime health](https://github.com/couchpugtato/vortex/blob/main/src/runtime_health.rs): `src/runtime_health.rs`
- [Runtime diagnostics](https://github.com/couchpugtato/vortex/blob/main/src/runtime_diagnostics.rs): `src/runtime_diagnostics.rs`

### Deployment

- [Deployment desktop app](https://github.com/couchpugtato/vortex/blob/main/VortexDeploymentInterface/main.js): `VortexDeploymentInterface/main.js`
- [Deployment interface](https://github.com/couchpugtato/vortex/blob/main/VortexDeploymentInterface/renderer/app.js): `VortexDeploymentInterface/renderer/app.js`
- [Release staging](https://github.com/couchpugtato/vortex/blob/main/VortexDeploymentInterface/staging-deploy.js): `VortexDeploymentInterface/staging-deploy.js`
- [Native deployment controller](https://github.com/couchpugtato/vortex/blob/main/deployment/src/main.rs): `deployment/src/main.rs`
- [Release activation](https://github.com/couchpugtato/vortex/blob/main/deployment/src/activation.rs): `deployment/src/activation.rs`
- [Service management](https://github.com/couchpugtato/vortex/blob/main/deployment/src/service.rs): `deployment/src/service.rs`

### Simulation and validation

- [Interactive simulator](https://github.com/couchpugtato/vortex/blob/main/chassis_sim/drive.py): `chassis_sim/drive.py`
- [Chassis routes](https://github.com/couchpugtato/vortex/blob/main/chassis_sim/routes.py): `chassis_sim/routes.py`
- [Ghost prediction](https://github.com/couchpugtato/vortex/blob/main/chassis_sim/ghost_prediction.py): `chassis_sim/ghost_prediction.py`
- [Field terrain](https://github.com/couchpugtato/vortex/blob/main/chassis_sim/terrain.py): `chassis_sim/terrain.py`
- [Failure capture and replay](https://github.com/couchpugtato/vortex/blob/main/chassis_sim/failure_capture.py): `chassis_sim/failure_capture.py`
- [Synthetic image generation](https://github.com/couchpugtato/vortex/blob/main/simulation_tests/generate.py): `simulation_tests/generate.py`
- [Native regression replay](https://github.com/couchpugtato/vortex/blob/main/simulation_tests/replay/src/main.rs): `simulation_tests/replay/src/main.rs`
- [Regression runner](https://github.com/couchpugtato/vortex/blob/main/simulation_tests/run.py): `simulation_tests/run.py`

### Calibration and acceleration

- [Intrinsics calibration](https://github.com/couchpugtato/vortex/blob/main/camera_calibration/camera_intrinsics_solver.py): `camera_calibration/camera_intrinsics_solver.py`
- [Distortion calibration](https://github.com/couchpugtato/vortex/blob/main/camera_calibration/camera_distortion_solver.py): `camera_calibration/camera_distortion_solver.py`
- [AprilTag calibration detection](https://github.com/couchpugtato/vortex/blob/main/camera_calibration/detect_apriltags.py): `camera_calibration/detect_apriltags.py`
- [TensorRT engine builder](https://github.com/couchpugtato/vortex/blob/main/model_builder/build_engine.cpp): `model_builder/build_engine.cpp`

### Other components

- **Operator**
- **Camera input**
- **Robot consumer**

## Connections

- Camera input → Vision pipeline: supplies frames
- Vision pipeline → Camera and field config: loads settings (evidence: `src/main.rs`)
- Vision pipeline → Image preprocessing: uses (evidence: `src/main.rs`)
- Vision pipeline → AprilTag detection: dispatches detection (evidence: `src/main.rs`)
- AprilTag detection → Tag refinement: builds patches (evidence: `src/detector.rs`)
- AprilTag detection → Pose estimation: estimates tag pose (evidence: `src/detector.rs`)
- Vision pipeline → Pose estimation: estimates robot pose (evidence: `src/main.rs`)
- Vision pipeline → GPU detection: uses optional backend (evidence: `src/main.rs`)
- Vision pipeline → VPI acceleration: uses optional acceleration (evidence: `src/main.rs`)
- Vision pipeline → TensorRT objects: dispatches object detection (evidence: `src/main.rs`)
- Vision pipeline → Runtime health: reports health (evidence: `src/main.rs`)
- Vision pipeline → Runtime diagnostics: collects diagnostics (evidence: `src/main.rs`)
- Vision pipeline → Robot consumer: publishes telemetry
- Operator → Deployment desktop app: configures deployment
- Deployment interface → Deployment desktop app: uses desktop services
- Deployment desktop app → Release staging: stages release (evidence: `VortexDeploymentInterface/main.js`)
- Release staging → Native deployment controller: uploads and invokes (evidence: `VortexDeploymentInterface/staging-deploy.js`)
- Native deployment controller → Release activation: activates release
- Native deployment controller → Service management: manages service (evidence: `deployment/src/service.rs`)
- Operator → Interactive simulator: drives simulation
- Interactive simulator → Chassis routes: loads route behavior (evidence: `chassis_sim/drive.py`)
- Interactive simulator → Ghost prediction: uses prediction (evidence: `chassis_sim/drive.py`)
- Interactive simulator → Field terrain: uses field terrain (evidence: `chassis_sim/drive.py`)
- Chassis routes → Field terrain: reads bumps (evidence: `chassis_sim/routes.py`)
- Chassis routes → Interactive simulator: uses motion step (evidence: `chassis_sim/routes.py`)
- Interactive simulator → Failure capture and replay: captures failures (evidence: `chassis_sim/drive.py`)
- Interactive simulator → Native regression replay: replays frames
- Regression runner → Synthetic image generation: generates scenarios (evidence: `simulation_tests/run.py`)
- Regression runner → Native regression replay: runs native replay (evidence: `simulation_tests/run.py`)
- Operator → Intrinsics calibration: calibrates camera
- Operator → Distortion calibration: calibrates distortion
- AprilTag calibration detection → Intrinsics calibration: provides tag observations
- TensorRT engine builder → TensorRT objects: builds inference engine
