# mortem1504/ai-guitar-tutor architecture

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

- Interactive diagram: https://gitdiagram.com/mortem1504/ai-guitar-tutor
- Repository: https://github.com/mortem1504/ai-guitar-tutor

## Overview

AI Guitar Chord Tutor is a local real-time coaching app: the user selects a lesson, starts camera and microphone processing, forms a chord, and strums; a success requires matching visual and acoustic evidence. The vision path detects guitar and fretboard, maps hand shape, and publishes observations; the audio path analyzes strums and chord tones. Shared state feeds timestamped fusion and evidence-based feedback displayed in the dashboard. README documents calibration, diagnostics, and training metrics; some subsystem links rely on README or SOURCE INDEX references because their source was not excerpted.

Main entry points: [`app.py`](https://github.com/mortem1504/ai-guitar-tutor/blob/main/app.py) (Streamlit dashboard), [`guitar_tutor/vision/video_processor.py`](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/video_processor.py) (Frame processing), [`guitar_tutor/state.py`](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/state.py) (Shared observations), [`guitar_tutor/fusion/evaluator.py`](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/fusion/evaluator.py) (Fusion evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Tutor experience"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
  node_ui["Tutor UI components<br/>[components.py]"]
  node_feedback["Measured feedback<br/>[feedback.py]"]
  node_diagnostics["Developer diagnostics<br/>[diagnostics.py]"]
end

subgraph group_vision["EYE vision"]
  node_camera["Camera capture<br/>[camera_manager.py]"]
  node_vision_worker["Vision worker<br/>[vision_worker.py]"]
  node_video["Frame processing<br/>[video_processor.py]"]
  node_guitar_detection["Guitar detection<br/>[guitar_detector.py]"]
  node_fret_detection["Fretboard detection"]
  node_fret_geometry["Fretboard geometry"]
  node_fret_mapping["Fretboard mapping"]
  node_calibration["Calibration settings"]
  node_hand_tracking["Hand landmarks"]
  node_hand_geometry["Hand geometry<br/>[hand_geometry.py]"]
  node_shape["Chord shape matching<br/>[chord_shape.py]"]
end

subgraph group_audio["EAR audio"]
  node_microphone["Microphone capture<br/>[microphone.py]"]
  node_chord_detector["Audio chord analysis<br/>[chord_detector.py]"]
  node_audio_helpers["DSP and onset tools"]
end

subgraph group_fusion["BRAIN fusion"]
  node_fusion_engine["Fusion evaluator<br/>[evaluator.py]"]
  node_event_sync["Strum synchronization<br/>[event_sync.py]"]
end

subgraph group_knowledge["Lesson and state"]
  node_shared_state["Shared observations<br/>[state.py]"]
  node_chord_library["Chord definitions<br/>[chord_library.py]"]
  node_config["Tutor configuration<br/>[config.py]"]
end

node_learner(("Guitar learner"))

node_learner -->|"chooses lesson"| node_dashboard
node_dashboard -->|"starts vision"| node_vision_worker
node_dashboard -->|"starts audio"| node_microphone
node_dashboard -->|"starts fusion"| node_fusion_engine
node_dashboard -->|"sets options"| node_config
node_dashboard -->|"renders dashboard"| node_ui
node_dashboard -->|"shows guidance"| node_feedback
node_dashboard -->|"shows diagnostics"| node_diagnostics
node_camera -->|"provides frames"| node_vision_worker
node_vision_worker -->|"processes frames"| node_video
node_vision_worker -->|"publishes results"| node_shared_state
node_video -->|"detects guitar"| node_guitar_detection
node_video -->|"detects fretboard"| node_fret_detection
node_fret_detection -->|"uses geometry"| node_fret_geometry
node_video -->|"tracks hands"| node_hand_tracking
node_video -->|"measures joints"| node_hand_geometry
node_video -->|"maps fingertips"| node_fret_mapping
node_fret_mapping -->|"uses calibration"| node_calibration
node_video -->|"classifies shape"| node_shape
node_shape -->|"matches fingerings"| node_chord_library
node_shape -->|"reads target state"| node_shared_state
node_microphone -->|"analyzes audio"| node_chord_detector
node_microphone -->|"publishes audio"| node_shared_state
node_chord_detector -->|"uses DSP tools"| node_audio_helpers
node_chord_detector -->|"compares templates"| node_chord_library
node_chord_detector -->|"uses thresholds"| node_config
node_fusion_engine -->|"reads observations"| node_shared_state
node_fusion_engine -->|"synchronizes strums"| node_event_sync
node_fusion_engine -->|"checks freshness"| node_config
node_ui -->|"renders snapshot"| node_shared_state
node_ui -->|"shows target tones"| node_chord_library
node_feedback -->|"reads measurements"| node_shared_state
node_feedback -->|"checks chord tones"| node_chord_library
node_shared_state -.->|"receives evaluation"| node_fusion_engine

click node_dashboard "https://github.com/mortem1504/ai-guitar-tutor/blob/main/app.py"
click node_ui "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/ui/components.py"
click node_feedback "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/tutor/feedback.py"
click node_diagnostics "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/tutor/diagnostics.py"
click node_camera "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/camera_manager.py"
click node_vision_worker "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/vision_worker.py"
click node_video "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/video_processor.py"
click node_guitar_detection "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/guitar_detector.py"
click node_fret_detection "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/fretboard_detector.py"
click node_fret_geometry "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/fretboard_geometry.py"
click node_fret_mapping "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/fretboard_mapper.py"
click node_calibration "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/fretboard_calibration.py"
click node_hand_tracking "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/mediapipe_adapter.py"
click node_hand_geometry "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/hand_geometry.py"
click node_shape "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/chord_shape.py"
click node_microphone "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/audio/microphone.py"
click node_chord_detector "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/audio/chord_detector.py"
click node_audio_helpers "https://github.com/mortem1504/ai-guitar-tutor/tree/main/guitar_tutor/audio"
click node_shared_state "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/state.py"
click node_chord_library "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/chord_library.py"
click node_config "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/config.py"
click node_fusion_engine "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/fusion/evaluator.py"
click node_event_sync "https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/fusion/event_sync.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_dashboard,node_ui,node_feedback,node_diagnostics toneBlue
class node_camera,node_vision_worker,node_video,node_guitar_detection,node_fret_detection,node_fret_geometry,node_fret_mapping,node_calibration,node_hand_tracking,node_hand_geometry,node_shape toneAmber
class node_microphone,node_chord_detector,node_audio_helpers toneMint
class node_fusion_engine,node_event_sync toneRose
class node_shared_state,node_chord_library,node_config,node_learner toneIndigo
```

## Components

### Tutor experience

- [Streamlit dashboard](https://github.com/mortem1504/ai-guitar-tutor/blob/main/app.py): `app.py`
- [Tutor UI components](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/ui/components.py): `guitar_tutor/ui/components.py`
- [Measured feedback](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/tutor/feedback.py): `guitar_tutor/tutor/feedback.py`
- [Developer diagnostics](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/tutor/diagnostics.py): `guitar_tutor/tutor/diagnostics.py`

### EYE vision

- [Camera capture](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/camera_manager.py): `guitar_tutor/vision/camera_manager.py`
- [Vision worker](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/vision_worker.py): `guitar_tutor/vision/vision_worker.py`
- [Frame processing](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/video_processor.py): `guitar_tutor/vision/video_processor.py`
- [Guitar detection](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/guitar_detector.py): `guitar_tutor/vision/guitar_detector.py`
- [Fretboard detection](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/fretboard_detector.py): `guitar_tutor/vision/fretboard_detector.py`
- [Fretboard geometry](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/fretboard_geometry.py): `guitar_tutor/vision/fretboard_geometry.py`
- [Fretboard mapping](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/fretboard_mapper.py): `guitar_tutor/vision/fretboard_mapper.py`
- [Calibration settings](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/fretboard_calibration.py): `guitar_tutor/vision/fretboard_calibration.py`
- [Hand landmarks](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/mediapipe_adapter.py): `guitar_tutor/vision/mediapipe_adapter.py`
- [Hand geometry](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/hand_geometry.py): `guitar_tutor/vision/hand_geometry.py`
- [Chord shape matching](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/vision/chord_shape.py): `guitar_tutor/vision/chord_shape.py`

### EAR audio

- [Microphone capture](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/audio/microphone.py): `guitar_tutor/audio/microphone.py`
- [Audio chord analysis](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/audio/chord_detector.py): `guitar_tutor/audio/chord_detector.py`
- [DSP and onset tools](https://github.com/mortem1504/ai-guitar-tutor/tree/main/guitar_tutor/audio): `guitar_tutor/audio`

### BRAIN fusion

- [Fusion evaluator](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/fusion/evaluator.py): `guitar_tutor/fusion/evaluator.py`
- [Strum synchronization](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/fusion/event_sync.py): `guitar_tutor/fusion/event_sync.py`

### Lesson and state

- [Shared observations](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/state.py): `guitar_tutor/state.py`
- [Chord definitions](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/chord_library.py): `guitar_tutor/chord_library.py`
- [Tutor configuration](https://github.com/mortem1504/ai-guitar-tutor/blob/main/guitar_tutor/config.py): `guitar_tutor/config.py`

### Other components

- **Guitar learner**

## Connections

- Guitar learner → Streamlit dashboard: chooses lesson (evidence: `README.md`)
- Streamlit dashboard → Vision worker: starts vision (evidence: `app.py`)
- Streamlit dashboard → Microphone capture: starts audio (evidence: `app.py`)
- Streamlit dashboard → Fusion evaluator: starts fusion (evidence: `app.py`)
- Streamlit dashboard → Tutor configuration: sets options (evidence: `app.py`)
- Streamlit dashboard → Tutor UI components: renders dashboard (evidence: `README.md`)
- Streamlit dashboard → Measured feedback: shows guidance (evidence: `README.md`)
- Streamlit dashboard → Developer diagnostics: shows diagnostics (evidence: `README.md`)
- Camera capture → Vision worker: provides frames (evidence: `guitar_tutor/vision/vision_worker.py`)
- Vision worker → Frame processing: processes frames (evidence: `guitar_tutor/vision/vision_worker.py`)
- Vision worker → Shared observations: publishes results (evidence: `guitar_tutor/vision/vision_worker.py`)
- Frame processing → Guitar detection: detects guitar (evidence: `guitar_tutor/vision/video_processor.py`)
- Frame processing → Fretboard detection: detects fretboard (evidence: `guitar_tutor/vision/video_processor.py`)
- Fretboard detection → Fretboard geometry: uses geometry (evidence: `guitar_tutor/vision/fretboard_detector.py`)
- Frame processing → Hand landmarks: tracks hands (evidence: `guitar_tutor/vision/video_processor.py`)
- Frame processing → Hand geometry: measures joints (evidence: `guitar_tutor/vision/video_processor.py`)
- Frame processing → Fretboard mapping: maps fingertips (evidence: `guitar_tutor/vision/video_processor.py`)
- Fretboard mapping → Calibration settings: uses calibration (evidence: `guitar_tutor/vision/fretboard_mapper.py`)
- Frame processing → Chord shape matching: classifies shape (evidence: `guitar_tutor/vision/video_processor.py`)
- Chord shape matching → Chord definitions: matches fingerings (evidence: `guitar_tutor/vision/chord_shape.py`)
- Chord shape matching → Shared observations: reads target state (evidence: `guitar_tutor/vision/chord_shape.py`)
- Microphone capture → Audio chord analysis: analyzes audio (evidence: `guitar_tutor/audio/microphone.py`)
- Microphone capture → Shared observations: publishes audio (evidence: `guitar_tutor/audio/microphone.py`)
- Audio chord analysis → DSP and onset tools: uses DSP tools (evidence: `guitar_tutor/audio/chord_detector.py`)
- Audio chord analysis → Chord definitions: compares templates (evidence: `guitar_tutor/audio/chord_detector.py`)
- Audio chord analysis → Tutor configuration: uses thresholds (evidence: `guitar_tutor/audio/chord_detector.py`)
- Fusion evaluator → Shared observations: reads observations (evidence: `guitar_tutor/fusion/evaluator.py`)
- Fusion evaluator → Strum synchronization: synchronizes strums (evidence: `guitar_tutor/fusion/evaluator.py`)
- Fusion evaluator → Tutor configuration: checks freshness (evidence: `guitar_tutor/fusion/evaluator.py`)
- Tutor UI components → Shared observations: renders snapshot (evidence: `guitar_tutor/ui/components.py`)
- Tutor UI components → Chord definitions: shows target tones (evidence: `guitar_tutor/ui/components.py`)
- Measured feedback → Shared observations: reads measurements (evidence: `guitar_tutor/tutor/feedback.py`)
- Measured feedback → Chord definitions: checks chord tones (evidence: `guitar_tutor/tutor/feedback.py`)
- Shared observations → Fusion evaluator: receives evaluation (evidence: `guitar_tutor/fusion/evaluator.py`)