# conorod1992/speaker-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/conorod1992/speaker-recognition
- Repository: https://github.com/conorod1992/speaker-recognition

## Overview

This repository delivers a two-part Home Assistant speaker-identification product: an integration that enrolls users and runs recognition alongside STT, and an HTTP app/add-on that trains and matches voice profiles. The main turn flow is supplemented by enrollment quality, calibration/review, live testing, diagnostics, and optional shadow-engine capabilities documented in the README. Edges cite the shown caller/import references or README; several integration and evaluation links remain unverified because their implementations were not excerpted.

Main entry points: [`speaker_recognition/api.py`](https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/api.py) (HTTP API), [`custom_components/speaker_recognition/telemetry.py`](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/telemetry.py) (Decision history), [`custom_components/speaker_recognition/stt.py`](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/stt.py) (STT coordination), [`custom_components/speaker_recognition/enrollment.py`](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/enrollment.py) (Enrollment capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ha["Home Assistant Integration"]
  node_integration["HA integration setup<br/>[config_flow.py]"]
  node_enrollment["Enrollment capture<br/>[enrollment.py]"]
  node_quality["Sample quality"]
  node_sttproxy["STT coordination<br/>[stt.py]"]
  node_recognition["Recognition request<br/>[recognition.py]"]
  node_turnproxy["Turn correlation<br/>[conversation.py]"]
end

subgraph group_service["Recognition Service"]
  node_backend["HTTP API<br/>[api.py]"]
  node_engine["Embedding engines<br/>[engines.py]"]
  node_recognizer["Profile matching<br/>[recognizer.py]"]
  node_profiledata[("Voice profiles<br/>[recognizer.py]")]
  node_shadow["Shadow recognition<br/>[shadow.py]"]
end

subgraph group_feedback["Evaluation and Calibration"]
  node_live["Live satellite evaluation<br/>[live_evaluation.py]"]
  node_history[("Decision history<br/>[telemetry.py]")]
  node_calibration["Threshold calibration<br/>[calibration.py]"]
  node_promotion["Profile promotion<br/>[promotions.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
end

subgraph group_ui["Panels"]
  node_panel["Enrollment panel"]
  node_calpanel["Calibration panel"]
  node_evalpanel["Evaluation panel"]
  node_settingspanel["Settings panel"]
end

node_user(("HA user"))
node_satellite(("Assist satellite"))
node_stt["STT provider"]
node_conversation["Conversation agent"]

node_user -->|"enrolls speakers"| node_panel
node_satellite -->|"provides samples"| node_enrollment
node_panel -.->|"stages recordings"| node_enrollment
node_enrollment -.->|"trains profiles"| node_backend
node_enrollment -->|"assesses samples"| node_quality
node_stt -->|"transcribes audio"| node_sttproxy
node_sttproxy -->|"runs concurrently"| node_recognition
node_recognition -->|"requests match"| node_backend
node_backend -->|"dispatches inference"| node_recognizer
node_recognizer -->|"creates embeddings"| node_engine
node_recognizer -->|"reads and updates"| node_profiledata
node_backend -->|"reports profiles"| node_profiledata
node_sttproxy -->|"correlates turn"| node_turnproxy
node_turnproxy -->|"attaches identity"| node_conversation
node_turnproxy -.->|"records decision"| node_history
node_sttproxy -->|"records recognition"| node_history
node_live -->|"observes Assist turn"| node_satellite
node_calpanel -->|"reviews decisions"| node_history
node_calpanel -.->|"applies thresholds"| node_calibration
node_calpanel -->|"promotes samples"| node_promotion
node_history -.->|"supplies feedback"| node_calibration
node_diagnostics -->|"reads decisions"| node_history
node_backend -->|"trains optionally"| node_shadow
node_evalpanel -.->|"views test results"| node_live
node_settingspanel -.->|"configures settings"| node_integration
node_panel -.->|"configures service"| node_integration

click node_integration "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/config_flow.py"
click node_enrollment "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/enrollment.py"
click node_quality "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/enrollment_quality.py"
click node_sttproxy "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/stt.py"
click node_recognition "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/recognition.py"
click node_turnproxy "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/conversation.py"
click node_backend "https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/api.py"
click node_engine "https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/engines.py"
click node_recognizer "https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/recognizer.py"
click node_profiledata "https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/recognizer.py"
click node_shadow "https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/shadow.py"
click node_live "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/live_evaluation.py"
click node_history "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/telemetry.py"
click node_calibration "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/calibration.py"
click node_promotion "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/promotions.py"
click node_diagnostics "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/diagnostics.py"
click node_panel "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/www/speaker-recognition-panel.js"
click node_calpanel "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/www/speaker-recognition-calibration-panel.js"
click node_evalpanel "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/www/speaker-recognition-evaluation-panel.js"
click node_settingspanel "https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/www/speaker-recognition-settings-panel.js"

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_integration,node_enrollment,node_quality,node_sttproxy,node_recognition,node_turnproxy,node_user toneBlue
class node_backend,node_engine,node_recognizer,node_profiledata,node_shadow toneAmber
class node_live,node_history,node_calibration,node_promotion,node_diagnostics toneMint
class node_panel,node_calpanel,node_evalpanel,node_settingspanel toneRose
class node_satellite,node_stt,node_conversation toneIndigo
```

## Components

### Home Assistant Integration

- [HA integration setup](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/config_flow.py): `custom_components/speaker_recognition/config_flow.py`
- [Enrollment capture](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/enrollment.py): `custom_components/speaker_recognition/enrollment.py`
- [Sample quality](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/enrollment_quality.py): `custom_components/speaker_recognition/enrollment_quality.py`
- [STT coordination](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/stt.py): `custom_components/speaker_recognition/stt.py`
- [Recognition request](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/recognition.py): `custom_components/speaker_recognition/recognition.py`
- [Turn correlation](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/conversation.py): `custom_components/speaker_recognition/conversation.py`

### Recognition Service

- [HTTP API](https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/api.py): `speaker_recognition/api.py`
- [Embedding engines](https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/engines.py): `speaker_recognition/engines.py`
- [Profile matching](https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/recognizer.py): `speaker_recognition/recognizer.py`
- [Voice profiles](https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/recognizer.py): `speaker_recognition/recognizer.py`
- [Shadow recognition](https://github.com/conorod1992/speaker-recognition/blob/master/speaker_recognition/shadow.py): `speaker_recognition/shadow.py`

### Evaluation and Calibration

- [Live satellite evaluation](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/live_evaluation.py): `custom_components/speaker_recognition/live_evaluation.py`
- [Decision history](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/telemetry.py): `custom_components/speaker_recognition/telemetry.py`
- [Threshold calibration](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/calibration.py): `custom_components/speaker_recognition/calibration.py`
- [Profile promotion](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/promotions.py): `custom_components/speaker_recognition/promotions.py`
- [Diagnostics](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/diagnostics.py): `custom_components/speaker_recognition/diagnostics.py`

### Panels

- [Enrollment panel](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/www/speaker-recognition-panel.js): `custom_components/speaker_recognition/www/speaker-recognition-panel.js`
- [Calibration panel](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/www/speaker-recognition-calibration-panel.js): `custom_components/speaker_recognition/www/speaker-recognition-calibration-panel.js`
- [Evaluation panel](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/www/speaker-recognition-evaluation-panel.js): `custom_components/speaker_recognition/www/speaker-recognition-evaluation-panel.js`
- [Settings panel](https://github.com/conorod1992/speaker-recognition/blob/master/custom_components/speaker_recognition/www/speaker-recognition-settings-panel.js): `custom_components/speaker_recognition/www/speaker-recognition-settings-panel.js`

### Other components

- **HA user**
- **Assist satellite**
- **STT provider**
- **Conversation agent**

## Connections

- HA user → Enrollment panel: enrolls speakers
- Assist satellite → Enrollment capture: provides samples
- Enrollment panel → Enrollment capture: stages recordings
- Enrollment capture → HTTP API: trains profiles
- Enrollment capture → Sample quality: assesses samples (evidence: `custom_components/speaker_recognition/enrollment_quality.py`)
- STT provider → STT coordination: transcribes audio
- STT coordination → Recognition request: runs concurrently (evidence: `custom_components/speaker_recognition/stt.py`)
- Recognition request → HTTP API: requests match (evidence: `custom_components/speaker_recognition/recognition.py`)
- HTTP API → Profile matching: dispatches inference (evidence: `speaker_recognition/api.py`)
- Profile matching → Embedding engines: creates embeddings (evidence: `speaker_recognition/recognizer.py`)
- Profile matching → Voice profiles: reads and updates (evidence: `speaker_recognition/recognizer.py`)
- HTTP API → Voice profiles: reports profiles (evidence: `speaker_recognition/api.py`)
- STT coordination → Turn correlation: correlates turn
- Turn correlation → Conversation agent: attaches identity
- Turn correlation → Decision history: records decision
- STT coordination → Decision history: records recognition (evidence: `custom_components/speaker_recognition/telemetry.py`)
- Live satellite evaluation → Assist satellite: observes Assist turn
- Calibration panel → Decision history: reviews decisions (evidence: `custom_components/speaker_recognition/www/speaker-recognition-calibration-panel.js`)
- Calibration panel → Threshold calibration: applies thresholds
- Calibration panel → Profile promotion: promotes samples (evidence: `custom_components/speaker_recognition/www/speaker-recognition-calibration-panel.js`)
- Decision history → Threshold calibration: supplies feedback
- Diagnostics → Decision history: reads decisions (evidence: `custom_components/speaker_recognition/diagnostics.py`)
- HTTP API → Shadow recognition: trains optionally (evidence: `speaker_recognition/api.py`)
- Evaluation panel → Live satellite evaluation: views test results
- Settings panel → HA integration setup: configures settings
- Enrollment panel → HA integration setup: configures service
