# andreaunali/signbridge architecture

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

- Interactive diagram: https://gitdiagram.com/andreaunali/signbridge
- Repository: https://github.com/andreaunali/signbridge

## Overview

SignBridge turns either typed English or recorded speech into an animated ASL gloss sequence. The runtime workflow is input selection, optional Whisper transcription, spaCy-based gloss conversion (including auxiliary filtering, lemmatization, and fingerspelling), pose lookup, then animation and video output. The shipped Pose directory is the precomputed sign dataset; README describes its one-time preparation, not a runtime stage. Animation internals are separated where the excerpts show distinct responsibilities; unsampled dataset-preparation implementation is not mapped.

Main entry points: [`main.py`](https://github.com/andreaunali/signbridge/blob/main/main.py) (CLI workflow), [`animation_lib.py`](https://github.com/andreaunali/signbridge/blob/main/animation_lib.py) (Animation director), [`INPUT_AUDIO`](https://github.com/andreaunali/signbridge/tree/main/INPUT_AUDIO) (Audio files), [`Pose`](https://github.com/andreaunali/signbridge/tree/main/Pose) (Pose JSON dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and language"]
  node_main["CLI workflow<br/>[main.py]"]
  node_audio["Audio files"]
  node_whisper["Whisper transcription"]
  node_text["Typed text<br/>[main.py]"]
  node_gloss["Gloss conversion<br/>[main.py]"]
  node_spacy["spaCy NLP"]
end

subgraph group_data["Sign pose data"]
  node_pose_data["Pose JSON dataset"]
end

subgraph group_animation["Animation and output"]
  node_director["Animation director<br/>[animation_lib.py]"]
  node_loader["Pose loader<br/>[animation_lib.py]"]
  node_normalization["Pose interpolation<br/>[animation_lib.py]"]
  node_transition["Sign transitions<br/>[animation_lib.py]"]
  node_renderer["Avatar renderer<br/>[animation_lib.py]"]
  node_video["MP4 output<br/>[animation_lib.py]"]
end

node_user(("User"))
node_opencv["OpenCV video I/O"]

node_user -->|"chooses input"| node_main
node_user -->|"provides audio"| node_audio
node_audio -->|"selects file"| node_main
node_main -->|"transcribes with"| node_whisper
node_user -->|"enters sentence"| node_text
node_text -->|"reads input"| node_main
node_main -->|"converts text"| node_gloss
node_gloss -->|"parses tokens"| node_spacy
node_gloss -->|"checks glosses"| node_pose_data
node_main -->|"renders sequence"| node_director
node_director -->|"loads poses"| node_loader
node_loader -->|"reads JSON"| node_pose_data
node_loader -->|"interpolates frames"| node_normalization
node_director -->|"creates bridges"| node_transition
node_director -->|"renders frames"| node_renderer
node_renderer -->|"draws with"| node_opencv
node_director -->|"writes video"| node_video
node_video -->|"uses writer"| node_opencv

click node_main "https://github.com/andreaunali/signbridge/blob/main/main.py"
click node_audio "https://github.com/andreaunali/signbridge/tree/main/INPUT_AUDIO"
click node_text "https://github.com/andreaunali/signbridge/blob/main/main.py"
click node_gloss "https://github.com/andreaunali/signbridge/blob/main/main.py"
click node_pose_data "https://github.com/andreaunali/signbridge/tree/main/Pose"
click node_director "https://github.com/andreaunali/signbridge/blob/main/animation_lib.py"
click node_loader "https://github.com/andreaunali/signbridge/blob/main/animation_lib.py"
click node_normalization "https://github.com/andreaunali/signbridge/blob/main/animation_lib.py"
click node_transition "https://github.com/andreaunali/signbridge/blob/main/animation_lib.py"
click node_renderer "https://github.com/andreaunali/signbridge/blob/main/animation_lib.py"
click node_video "https://github.com/andreaunali/signbridge/blob/main/animation_lib.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_main,node_audio,node_whisper,node_text,node_gloss,node_spacy,node_user toneBlue
class node_pose_data toneAmber
class node_director,node_loader,node_normalization,node_transition,node_renderer,node_video toneMint
class node_opencv toneIndigo
```

## Components

### Input and language

- [CLI workflow](https://github.com/andreaunali/signbridge/blob/main/main.py): `main.py`
- [Audio files](https://github.com/andreaunali/signbridge/tree/main/INPUT_AUDIO): `INPUT_AUDIO`
- **Whisper transcription**
- [Typed text](https://github.com/andreaunali/signbridge/blob/main/main.py): `main.py`
- [Gloss conversion](https://github.com/andreaunali/signbridge/blob/main/main.py): `main.py`
- **spaCy NLP**

### Sign pose data

- [Pose JSON dataset](https://github.com/andreaunali/signbridge/tree/main/Pose): `Pose`

### Animation and output

- [Animation director](https://github.com/andreaunali/signbridge/blob/main/animation_lib.py): `animation_lib.py`
- [Pose loader](https://github.com/andreaunali/signbridge/blob/main/animation_lib.py): `animation_lib.py`
- [Pose interpolation](https://github.com/andreaunali/signbridge/blob/main/animation_lib.py): `animation_lib.py`
- [Sign transitions](https://github.com/andreaunali/signbridge/blob/main/animation_lib.py): `animation_lib.py`
- [Avatar renderer](https://github.com/andreaunali/signbridge/blob/main/animation_lib.py): `animation_lib.py`
- [MP4 output](https://github.com/andreaunali/signbridge/blob/main/animation_lib.py): `animation_lib.py`

### Other components

- **User**
- **OpenCV video I/O**

## Connections

- User → CLI workflow: chooses input (evidence: `main.py`)
- User → Audio files: provides audio
- Audio files → CLI workflow: selects file (evidence: `main.py`)
- CLI workflow → Whisper transcription: transcribes with (evidence: `main.py`)
- User → Typed text: enters sentence
- Typed text → CLI workflow: reads input (evidence: `main.py`)
- CLI workflow → Gloss conversion: converts text (evidence: `main.py`)
- Gloss conversion → spaCy NLP: parses tokens (evidence: `main.py`)
- Gloss conversion → Pose JSON dataset: checks glosses (evidence: `main.py`)
- CLI workflow → Animation director: renders sequence (evidence: `main.py`)
- Animation director → Pose loader: loads poses (evidence: `animation_lib.py`)
- Pose loader → Pose JSON dataset: reads JSON (evidence: `animation_lib.py`)
- Pose loader → Pose interpolation: interpolates frames (evidence: `animation_lib.py`)
- Animation director → Sign transitions: creates bridges (evidence: `animation_lib.py`)
- Animation director → Avatar renderer: renders frames (evidence: `animation_lib.py`)
- Avatar renderer → OpenCV video I/O: draws with (evidence: `animation_lib.py`)
- Animation director → MP4 output: writes video (evidence: `animation_lib.py`)
- MP4 output → OpenCV video I/O: uses writer (evidence: `animation_lib.py`)
