# jose-alba/stealth_mouse architecture

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

- Interactive diagram: https://gitdiagram.com/jose-alba/stealth_mouse
- Repository: https://github.com/jose-alba/stealth_mouse

## Overview

Stealth Mouse records human mouse gestures, retrieves a matching recorded path for a requested movement, transforms and interpolates it, then dispatches movement and (for native use) clicks. The README also describes interactive target verification and browser automation. Recorder and playback wiring is supported by the sampled source; browser support is documented and partly visible in the player, but its integration is not fully sampled.

Main entry points: [`src/player.py`](https://github.com/jose-alba/stealth_mouse/blob/main/src/player.py) (Movement player), [`src/indexer.py`](https://github.com/jose-alba/stealth_mouse/blob/main/src/indexer.py) (Trajectory lookup), [`src/recorder.py`](https://github.com/jose-alba/stealth_mouse/blob/main/src/recorder.py) (Gesture recorder), [`example.py`](https://github.com/jose-alba/stealth_mouse/blob/main/example.py) (Target practice UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Gesture capture"]
  node_recorder["Gesture recorder<br/>[recorder.py]"]
  node_indexdata[("Trajectory index")]
  node_pointsdata[("Coordinate bank")]
end

subgraph group_playback["Trajectory playback"]
  node_main["Move / click API<br/>[main.py]"]
  node_player["Movement player<br/>[player.py]"]
  node_indexer["Trajectory lookup<br/>[indexer.py]"]
  node_transformer["Path transform<br/>[transformer.py]"]
  node_interpolator["Spline sampling<br/>[interpolator.py]"]
end

subgraph group_dispatch["Input dispatch"]
  node_osmouse(("Native mouse"))
  node_browser(("Browser page"))
end

subgraph group_verification["Visual verification"]
  node_example["Target practice UI<br/>[example.py]"]
  node_screen(("Desktop display"))
end

node_user(("User / caller"))

node_user -->|"requests move/click"| node_main
node_main -->|"calls"| node_player
node_player -->|"reads position"| node_osmouse
node_player -->|"queries candidates"| node_indexer
node_indexer -->|"loads descriptors"| node_indexdata
node_indexer -->|"loads points"| node_pointsdata
node_indexer -->|"returns match"| node_player
node_player -->|"transforms path"| node_transformer
node_player -->|"samples path"| node_interpolator
node_player -->|"dispatches movement/click"| node_osmouse
node_player -.->|"dispatches async input"| node_browser
node_user -->|"starts recording"| node_recorder
node_osmouse -->|"sends events"| node_recorder
node_recorder -->|"writes index"| node_indexdata
node_recorder -->|"writes coordinates"| node_pointsdata
node_user -->|"runs verification"| node_example
node_example -->|"calls click"| node_main
node_example -->|"draws targets/status"| node_screen

click node_main "https://github.com/jose-alba/stealth_mouse/blob/main/main.py"
click node_player "https://github.com/jose-alba/stealth_mouse/blob/main/src/player.py"
click node_indexer "https://github.com/jose-alba/stealth_mouse/blob/main/src/indexer.py"
click node_transformer "https://github.com/jose-alba/stealth_mouse/blob/main/src/transformer.py"
click node_interpolator "https://github.com/jose-alba/stealth_mouse/blob/main/src/interpolator.py"
click node_recorder "https://github.com/jose-alba/stealth_mouse/blob/main/src/recorder.py"
click node_indexdata "https://github.com/jose-alba/stealth_mouse/blob/main/data/trajectories_index.npz"
click node_pointsdata "https://github.com/jose-alba/stealth_mouse/blob/main/data/trajectories_points.npz"
click node_example "https://github.com/jose-alba/stealth_mouse/blob/main/example.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_recorder,node_indexdata,node_pointsdata,node_user toneBlue
class node_main,node_player,node_indexer,node_transformer,node_interpolator toneAmber
class node_osmouse,node_browser toneMint
class node_example,node_screen toneRose
```

## Components

### Gesture capture

- [Gesture recorder](https://github.com/jose-alba/stealth_mouse/blob/main/src/recorder.py): `src/recorder.py`
- [Trajectory index](https://github.com/jose-alba/stealth_mouse/blob/main/data/trajectories_index.npz): `data/trajectories_index.npz`
- [Coordinate bank](https://github.com/jose-alba/stealth_mouse/blob/main/data/trajectories_points.npz): `data/trajectories_points.npz`

### Trajectory playback

- [Move / click API](https://github.com/jose-alba/stealth_mouse/blob/main/main.py): `main.py`
- [Movement player](https://github.com/jose-alba/stealth_mouse/blob/main/src/player.py): `src/player.py`
- [Trajectory lookup](https://github.com/jose-alba/stealth_mouse/blob/main/src/indexer.py): `src/indexer.py`
- [Path transform](https://github.com/jose-alba/stealth_mouse/blob/main/src/transformer.py): `src/transformer.py`
- [Spline sampling](https://github.com/jose-alba/stealth_mouse/blob/main/src/interpolator.py): `src/interpolator.py`

### Input dispatch

- **Native mouse**
- **Browser page**

### Visual verification

- [Target practice UI](https://github.com/jose-alba/stealth_mouse/blob/main/example.py): `example.py`
- **Desktop display**

### Other components

- **User / caller**

## Connections

- User / caller → Move / click API: requests move/click
- Move / click API → Movement player: calls
- Movement player → Native mouse: reads position
- Movement player → Trajectory lookup: queries candidates
- Trajectory lookup → Trajectory index: loads descriptors
- Trajectory lookup → Coordinate bank: loads points
- Trajectory lookup → Movement player: returns match
- Movement player → Path transform: transforms path
- Movement player → Spline sampling: samples path
- Movement player → Native mouse: dispatches movement/click
- Movement player → Browser page: dispatches async input
- User / caller → Gesture recorder: starts recording
- Native mouse → Gesture recorder: sends events
- Gesture recorder → Trajectory index: writes index
- Gesture recorder → Coordinate bank: writes coordinates
- User / caller → Target practice UI: runs verification
- Target practice UI → Move / click API: calls click
- Target practice UI → Desktop display: draws targets/status