# uzankhan/swordflow architecture

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

- Interactive diagram: https://gitdiagram.com/uzankhan/swordflow
- Repository: https://github.com/uzankhan/swordflow

## Overview

Swordflow turns camera or mouse input into a live motion-controlled 3D experience: the user enters a mode, hand tracking can acquire camera access and interpret local vision results as gesture signals, and the scene responds with sword-swarm or dragon gameplay. The main controller coordinates controls and routes signals into the world renderer. The README also documents formations, volley outcomes and recall, dragon recentering, pause, and tracking cancellation. Source excerpts show the worker/tracker and scene integration; unsampled implementation details are represented only where documented.

Main entry points: [`src/hand/HandTracker.ts`](https://github.com/uzankhan/swordflow/blob/main/src/hand/HandTracker.ts) (Camera lifecycle), [`src/scene/SwordWorld.ts`](https://github.com/uzankhan/swordflow/blob/main/src/scene/SwordWorld.ts) (World simulation), [`src/main.ts`](https://github.com/uzankhan/swordflow/blob/main/src/main.ts) (Experience controller), [`src/hand/inference.worker.ts`](https://github.com/uzankhan/swordflow/blob/main/src/hand/inference.worker.ts) (Vision inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Experience control"]
  node_ui["Experience controller<br/>[main.ts]"]
  node_mouse["Mouse input<br/>[main.ts]"]
end

subgraph group_tracking["Local hand tracking"]
  node_camera["Camera stream"]
  node_tracker["Camera lifecycle<br/>[HandTracker.ts]"]
  node_worker["Vision inference"]
  node_types["Vision messages<br/>[vision-types.ts]"]
  node_interpreter["Gesture interpretation<br/>[gesture.ts]"]
end

subgraph group_world["3D world and modes"]
  node_world["World simulation<br/>[SwordWorld.ts]"]
  node_swords["Sword swarm<br/>[SwordWorld.ts]"]
  node_dragon["Procedural dragon<br/>[DragonFlight.ts]"]
end

node_user(("Player"))
node_mediapipe["MediaPipe Vision"]

node_user -->|"chooses mode"| node_ui
node_ui -->|"starts tracking"| node_tracker
node_tracker -->|"requests frames"| node_camera
node_tracker -->|"dispatches frames"| node_worker
node_worker -->|"runs inference"| node_mediapipe
node_worker -->|"returns results"| node_tracker
node_tracker -->|"interprets poses"| node_interpreter
node_interpreter -->|"uses vision data"| node_types
node_worker -->|"serializes results"| node_types
node_ui -->|"routes hand signals"| node_world
node_ui -->|"accepts fallback"| node_mouse
node_mouse -->|"steers simulation"| node_world
node_world -->|"simulates swarm"| node_swords
node_world -->|"updates dragon"| node_dragon
node_dragon -->|"adds scene object"| node_world
node_user -->|"grants permission"| node_camera

click node_ui "https://github.com/uzankhan/swordflow/blob/main/src/main.ts"
click node_tracker "https://github.com/uzankhan/swordflow/blob/main/src/hand/HandTracker.ts"
click node_worker "https://github.com/uzankhan/swordflow/blob/main/src/hand/inference.worker.ts"
click node_types "https://github.com/uzankhan/swordflow/blob/main/src/hand/vision-types.ts"
click node_interpreter "https://github.com/uzankhan/swordflow/blob/main/src/hand/gesture.ts"
click node_world "https://github.com/uzankhan/swordflow/blob/main/src/scene/SwordWorld.ts"
click node_swords "https://github.com/uzankhan/swordflow/blob/main/src/scene/SwordWorld.ts"
click node_dragon "https://github.com/uzankhan/swordflow/blob/main/src/scene/DragonFlight.ts"
click node_mouse "https://github.com/uzankhan/swordflow/blob/main/src/main.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_ui,node_mouse toneBlue
class node_camera,node_tracker,node_worker,node_types,node_interpreter toneAmber
class node_world,node_swords,node_dragon,node_mediapipe toneMint
class node_user toneIndigo
```

## Components

### Experience control

- [Experience controller](https://github.com/uzankhan/swordflow/blob/main/src/main.ts): `src/main.ts`
- [Mouse input](https://github.com/uzankhan/swordflow/blob/main/src/main.ts): `src/main.ts`

### Local hand tracking

- **Camera stream**
- [Camera lifecycle](https://github.com/uzankhan/swordflow/blob/main/src/hand/HandTracker.ts): `src/hand/HandTracker.ts`
- [Vision inference](https://github.com/uzankhan/swordflow/blob/main/src/hand/inference.worker.ts): `src/hand/inference.worker.ts`
- [Vision messages](https://github.com/uzankhan/swordflow/blob/main/src/hand/vision-types.ts): `src/hand/vision-types.ts`
- [Gesture interpretation](https://github.com/uzankhan/swordflow/blob/main/src/hand/gesture.ts): `src/hand/gesture.ts`

### 3D world and modes

- [World simulation](https://github.com/uzankhan/swordflow/blob/main/src/scene/SwordWorld.ts): `src/scene/SwordWorld.ts`
- [Sword swarm](https://github.com/uzankhan/swordflow/blob/main/src/scene/SwordWorld.ts): `src/scene/SwordWorld.ts`
- [Procedural dragon](https://github.com/uzankhan/swordflow/blob/main/src/scene/DragonFlight.ts): `src/scene/DragonFlight.ts`

### Other components

- **Player**
- **MediaPipe Vision**

## Connections

- Player → Experience controller: chooses mode (evidence: `README.md`)
- Experience controller → Camera lifecycle: starts tracking (evidence: `src/main.ts`)
- Camera lifecycle → Camera stream: requests frames (evidence: `src/hand/HandTracker.ts`)
- Camera lifecycle → Vision inference: dispatches frames (evidence: `src/hand/HandTracker.ts`)
- Vision inference → MediaPipe Vision: runs inference (evidence: `src/hand/inference.worker.ts`)
- Vision inference → Camera lifecycle: returns results (evidence: `src/hand/inference.worker.ts`)
- Camera lifecycle → Gesture interpretation: interprets poses (evidence: `src/hand/HandTracker.ts`)
- Gesture interpretation → Vision messages: uses vision data (evidence: `src/hand/gesture.ts`)
- Vision inference → Vision messages: serializes results (evidence: `src/hand/inference.worker.ts`)
- Experience controller → World simulation: routes hand signals (evidence: `src/main.ts`)
- Experience controller → Mouse input: accepts fallback (evidence: `README.md`)
- Mouse input → World simulation: steers simulation (evidence: `README.md`)
- World simulation → Sword swarm: simulates swarm (evidence: `src/scene/SwordWorld.ts`)
- World simulation → Procedural dragon: updates dragon (evidence: `src/scene/SwordWorld.ts`)
- Procedural dragon → World simulation: adds scene object (evidence: `src/scene/DragonFlight.ts`)
- Player → Camera stream: grants permission (evidence: `README.md`)
