# joker-qp/ando-sign3d architecture

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

- Interactive diagram: https://gitdiagram.com/joker-qp/ando-sign3d
- Repository: https://github.com/joker-qp/ando-sign3d

## Overview

This repository contains an ASL fingerspelling research workflow: curate hand-image data, prepare normalized landmarks, train a 26-letter classifier, evaluate it, and export model artifacts. A live-camera inference module is present, though its implementation was not sampled, so its runtime details and wiring are limited to documented responsibilities. The sampled sources support the training pipeline’s use of curation, normalization, model, and academic-support modules; the tree and model documentation identify the remaining product capabilities.

Main entry points: [`src/models/m01_asl_letters/train.py`](https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/train.py) (Training pipeline), [`artifacts/m01_asl_letters`](https://github.com/joker-qp/ando-sign3d/tree/main/artifacts/m01_asl_letters) (Model and reports), [`src/common/io_manifest_reader.py`](https://github.com/joker-qp/ando-sign3d/blob/main/src/common/io_manifest_reader.py) (Curation and splits), [`src/models/m01_asl_letters/test_cam.py`](https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/test_cam.py) (Camera inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_curation["Curation and splits"]
  node_prep_config["Curation rules"]
  node_manifests["Curated manifests"]
  node_landmarks["Landmark preparation<br/>[train.py]"]
  node_normalizer["Pose normalization<br/>[math_normalizer.py]"]
end

subgraph group_modeling["Model workflow"]
  node_train["Training pipeline<br/>[train.py]"]
  node_model_config["Model settings"]
  node_classifier["ASL classifier<br/>[model.py]"]
end

subgraph group_research["Research outputs"]
  node_evaluator["Academic evaluation"]
  node_tracker["Experiment telemetry<br/>[academic_logger.py]"]
  node_model_card["Model card generation"]
  node_artifacts["Model and reports"]
  node_qa_report["Dataset QA report"]
end

subgraph group_inference["Live inference"]
  node_live["Camera inference<br/>[test_cam.py]"]
end

node_dataset["ASL images"]
node_camera(("Camera user"))

node_dataset -->|"provides images"| node_curation
node_prep_config -->|"configures"| node_curation
node_curation -->|"writes manifests"| node_manifests
node_train -->|"runs if missing"| node_curation
node_manifests -->|"loads data"| node_train
node_train -->|"extracts landmarks"| node_landmarks
node_landmarks -->|"normalizes poses"| node_normalizer
node_model_config -->|"configures"| node_train
node_train -->|"trains and exports"| node_classifier
node_train -->|"logs experiment"| node_tracker
node_train -->|"evaluates model"| node_evaluator
node_train -->|"generates card"| node_model_card
node_train -->|"writes outputs"| node_artifacts
node_evaluator -->|"writes evaluation"| node_artifacts
node_tracker -->|"writes metrics"| node_artifacts
node_model_card -->|"reads run outputs"| node_artifacts
node_manifests -->|"reads manifests"| node_qa_report
node_camera -->|"provides camera input"| node_live
node_normalizer -->|"normalizes poses"| node_live
node_classifier -->|"classifies landmarks"| node_live
node_artifacts -.->|"provides exported model"| node_live

click node_curation "https://github.com/joker-qp/ando-sign3d/blob/main/src/common/io_manifest_reader.py"
click node_prep_config "https://github.com/joker-qp/ando-sign3d/blob/main/configs/preprocessing_rules.yaml"
click node_landmarks "https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/train.py"
click node_normalizer "https://github.com/joker-qp/ando-sign3d/blob/main/src/common/math_normalizer.py"
click node_train "https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/train.py"
click node_model_config "https://github.com/joker-qp/ando-sign3d/blob/main/configs/models/m01_asl_letters.yaml"
click node_classifier "https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/model.py"
click node_evaluator "https://github.com/joker-qp/ando-sign3d/blob/main/src/common/academic_evaluator.py"
click node_tracker "https://github.com/joker-qp/ando-sign3d/blob/main/src/common/academic_logger.py"
click node_model_card "https://github.com/joker-qp/ando-sign3d/blob/main/src/common/report_generator.py"
click node_artifacts "https://github.com/joker-qp/ando-sign3d/tree/main/artifacts/m01_asl_letters"
click node_qa_report "https://github.com/joker-qp/ando-sign3d/blob/main/src/tools/generate_dataset_qa_report.py"
click node_live "https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/test_cam.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_curation,node_prep_config,node_manifests,node_landmarks,node_normalizer,node_camera toneBlue
class node_train,node_model_config,node_classifier toneAmber
class node_evaluator,node_tracker,node_model_card,node_artifacts,node_qa_report toneMint
class node_live toneRose
class node_dataset toneIndigo
```

## Components

### Data preparation

- [Curation and splits](https://github.com/joker-qp/ando-sign3d/blob/main/src/common/io_manifest_reader.py): `src/common/io_manifest_reader.py`
- [Curation rules](https://github.com/joker-qp/ando-sign3d/blob/main/configs/preprocessing_rules.yaml): `configs/preprocessing_rules.yaml`
- **Curated manifests**
- [Landmark preparation](https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/train.py): `src/models/m01_asl_letters/train.py`
- [Pose normalization](https://github.com/joker-qp/ando-sign3d/blob/main/src/common/math_normalizer.py): `src/common/math_normalizer.py`

### Model workflow

- [Training pipeline](https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/train.py): `src/models/m01_asl_letters/train.py`
- [Model settings](https://github.com/joker-qp/ando-sign3d/blob/main/configs/models/m01_asl_letters.yaml): `configs/models/m01_asl_letters.yaml`
- [ASL classifier](https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/model.py): `src/models/m01_asl_letters/model.py`

### Research outputs

- [Academic evaluation](https://github.com/joker-qp/ando-sign3d/blob/main/src/common/academic_evaluator.py): `src/common/academic_evaluator.py`
- [Experiment telemetry](https://github.com/joker-qp/ando-sign3d/blob/main/src/common/academic_logger.py): `src/common/academic_logger.py`
- [Model card generation](https://github.com/joker-qp/ando-sign3d/blob/main/src/common/report_generator.py): `src/common/report_generator.py`
- [Model and reports](https://github.com/joker-qp/ando-sign3d/tree/main/artifacts/m01_asl_letters): `artifacts/m01_asl_letters`
- [Dataset QA report](https://github.com/joker-qp/ando-sign3d/blob/main/src/tools/generate_dataset_qa_report.py): `src/tools/generate_dataset_qa_report.py`

### Live inference

- [Camera inference](https://github.com/joker-qp/ando-sign3d/blob/main/src/models/m01_asl_letters/test_cam.py): `src/models/m01_asl_letters/test_cam.py`

### Other components

- **ASL images**
- **Camera user**

## Connections

- ASL images → Curation and splits: provides images
- Curation rules → Curation and splits: configures
- Curation and splits → Curated manifests: writes manifests
- Training pipeline → Curation and splits: runs if missing
- Curated manifests → Training pipeline: loads data
- Training pipeline → Landmark preparation: extracts landmarks
- Landmark preparation → Pose normalization: normalizes poses
- Model settings → Training pipeline: configures
- Training pipeline → ASL classifier: trains and exports
- Training pipeline → Experiment telemetry: logs experiment
- Training pipeline → Academic evaluation: evaluates model
- Training pipeline → Model card generation: generates card
- Training pipeline → Model and reports: writes outputs
- Academic evaluation → Model and reports: writes evaluation
- Experiment telemetry → Model and reports: writes metrics
- Model card generation → Model and reports: reads run outputs
- Curated manifests → Dataset QA report: reads manifests
- Camera user → Camera inference: provides camera input
- Pose normalization → Camera inference: normalizes poses
- ASL classifier → Camera inference: classifies landmarks
- Model and reports → Camera inference: provides exported model