# welcomyou/sherpa-vietnamese-asr architecture

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

- Interactive diagram: https://gitdiagram.com/welcomyou/sherpa-vietnamese-asr
- Repository: https://github.com/welcomyou/sherpa-vietnamese-asr

## Overview

Sherpa Vietnamese ASR is an offline-first Vietnamese transcription product with desktop and web-service interfaces. The main workflow is audio submission, decoding and ASR, followed by optional punctuation, speaker diarization, overlap separation, and quality analysis; users can review and edit results. The web service adds authenticated sessions, queued jobs, persistence, and meeting/search features. README documents an offline PWA, but the sampled browser pipeline explicitly says inference is not implemented in the baseline scaffold. Some subsystem links below are documented capabilities rather than inspected call paths.

Main entry points: [`core/asr_engine.py`](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/asr_engine.py) (ASR engine), [`web_service/server.py`](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/server.py) (Web API), [`app.py`](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/app.py) (Desktop app), [`web_service/queue_manager.py`](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/queue_manager.py) (Job queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop_app["Desktop app<br/>[app.py]"]
  node_file_ui["File transcription<br/>[tab_file.py]"]
  node_live_ui["Live recording<br/>[tab_live.py]"]
end

subgraph group_recognition["Recognition pipeline"]
  node_transcriber["Transcriber pipeline<br/>[transcriber.py]"]
  node_asr["ASR engine<br/>[asr_engine.py]"]
  node_audio_decode["Audio decoding<br/>[audio_decode.py]"]
  node_vad["Voice activity detection<br/>[vad_utils.py]"]
  node_punctuation["Punctuation restoration"]
  node_diarization["Speaker diarization"]
  node_campp["CAM++ diarization"]
  node_overlap["Overlap separation"]
  node_quality["Audio quality<br/>[audio_analyzer.py]"]
end

subgraph group_web["Web service"]
  node_web_server["Web API<br/>[server.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_sessions["Session lifecycle<br/>[session_manager.py]"]
  node_queue["Job queue<br/>[queue_manager.py]"]
  node_database[("Service database<br/>[database.py]")]
  node_summarizer["Meeting summarizer<br/>[summarizer.py]"]
end

subgraph group_pwa["Offline PWA"]
  node_pwa_server["PWA file server<br/>[server.py]"]
  node_pwa_pipeline["Browser pipeline scaffold<br/>[pipeline.ts]"]
end

subgraph group_runtime["Runtime and acceleration"]
  node_config["Model and app config<br/>[config.py]"]
  node_calibration["GPU calibration<br/>[calibration.py]"]
  node_hardware["Hardware providers<br/>[hardware_accel.py]"]
  node_web_config["Service config<br/>[config.py]"]
end

node_desktop_user(("Desktop user"))
node_web_user(("Web user"))

node_desktop_user -->|"opens"| node_desktop_app
node_desktop_app -->|"offers file workflow"| node_file_ui
node_desktop_app -->|"offers recording"| node_live_ui
node_file_ui -->|"invokes"| node_asr
node_file_ui -->|"uses"| node_audio_decode
node_live_ui -->|"analyzes audio"| node_quality
node_asr -->|"decodes through"| node_audio_decode
node_asr -->|"uses"| node_vad
node_asr -->|"uses"| node_punctuation
node_asr -->|"uses"| node_diarization
node_asr -->|"uses"| node_campp
node_asr -->|"uses"| node_overlap
node_desktop_user -->|"submits audio"| node_file_ui
node_web_user -->|"uploads audio"| node_web_server
node_web_server -->|"checks access"| node_auth
node_web_server -->|"tracks sessions"| node_sessions
node_web_server -->|"enqueues jobs"| node_queue
node_queue -->|"updates jobs"| node_database
node_queue -->|"runs transcription"| node_asr
node_queue -->|"dispatches summaries"| node_summarizer
node_web_server -->|"reads and writes"| node_database
node_sessions -->|"stores session state"| node_database
node_web_server -->|"requests calibration"| node_calibration
node_calibration -->|"detects providers"| node_hardware
node_calibration -->|"benchmarks stages"| node_asr
node_desktop_app -->|"loads settings"| node_config
node_asr -->|"reads model settings"| node_config
node_web_server -->|"uses settings"| node_web_config
node_web_config -->|"shares model config"| node_config
node_web_user -->|"opens offline app"| node_pwa_server
node_pwa_server -.->|"serves browser shell"| node_pwa_pipeline
node_pwa_pipeline -.->|"inference not implemented"| node_asr
node_asr -.->|"evaluates quality"| node_quality
node_asr -->|"restores punctuation"| node_punctuation
node_asr -->|"assigns speakers"| node_diarization
node_asr -->|"separates overlap"| node_overlap

click node_desktop_app "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/app.py"
click node_file_ui "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/tab_file.py"
click node_live_ui "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/tab_live.py"
click node_transcriber "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/transcriber.py"
click node_asr "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/asr_engine.py"
click node_audio_decode "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/audio_decode.py"
click node_vad "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/vad_utils.py"
click node_punctuation "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/punctuation_restorer_improved.py"
click node_diarization "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/speaker_diarization_pure_ort.py"
click node_campp "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/speaker_diarization_senko_campp.py"
click node_overlap "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/overlap_separator.py"
click node_quality "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/audio_analyzer.py"
click node_web_server "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/server.py"
click node_auth "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/auth.py"
click node_sessions "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/session_manager.py"
click node_queue "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/queue_manager.py"
click node_database "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/database.py"
click node_summarizer "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/summarizer.py"
click node_pwa_server "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/offline_pwa/server.py"
click node_pwa_pipeline "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/offline_pwa/src/engine/pipeline.ts"
click node_config "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/config.py"
click node_calibration "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/calibration.py"
click node_hardware "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/hardware_accel.py"
click node_web_config "https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/config.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_desktop_app,node_file_ui,node_live_ui,node_desktop_user,node_web_user toneBlue
class node_transcriber,node_asr,node_audio_decode,node_vad,node_punctuation,node_diarization,node_campp,node_overlap,node_quality toneAmber
class node_web_server,node_auth,node_sessions,node_queue,node_database,node_summarizer toneMint
class node_pwa_server,node_pwa_pipeline toneRose
class node_config,node_calibration,node_hardware,node_web_config toneIndigo
```

## Components

### Desktop experience

- [Desktop app](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/app.py): `app.py`
- [File transcription](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/tab_file.py): `tab_file.py`
- [Live recording](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/tab_live.py): `tab_live.py`

### Recognition pipeline

- [Transcriber pipeline](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/transcriber.py): `transcriber.py`
- [ASR engine](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/asr_engine.py): `core/asr_engine.py`
- [Audio decoding](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/audio_decode.py): `core/audio_decode.py`
- [Voice activity detection](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/vad_utils.py): `core/vad_utils.py`
- [Punctuation restoration](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/punctuation_restorer_improved.py): `core/punctuation_restorer_improved.py`
- [Speaker diarization](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/speaker_diarization_pure_ort.py): `core/speaker_diarization_pure_ort.py`
- [CAM++ diarization](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/speaker_diarization_senko_campp.py): `core/speaker_diarization_senko_campp.py`
- [Overlap separation](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/overlap_separator.py): `core/overlap_separator.py`
- [Audio quality](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/audio_analyzer.py): `core/audio_analyzer.py`

### Web service

- [Web API](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/server.py): `web_service/server.py`
- [Authentication](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/auth.py): `web_service/auth.py`
- [Session lifecycle](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/session_manager.py): `web_service/session_manager.py`
- [Job queue](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/queue_manager.py): `web_service/queue_manager.py`
- [Service database](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/database.py): `web_service/database.py`
- [Meeting summarizer](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/summarizer.py): `web_service/summarizer.py`

### Offline PWA

- [PWA file server](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/offline_pwa/server.py): `offline_pwa/server.py`
- [Browser pipeline scaffold](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/offline_pwa/src/engine/pipeline.ts): `offline_pwa/src/engine/pipeline.ts`

### Runtime and acceleration

- [Model and app config](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/config.py): `core/config.py`
- [GPU calibration](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/calibration.py): `core/calibration.py`
- [Hardware providers](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/core/hardware_accel.py): `core/hardware_accel.py`
- [Service config](https://github.com/welcomyou/sherpa-vietnamese-asr/blob/main/web_service/config.py): `web_service/config.py`

### Other components

- **Desktop user**
- **Web user**

## Connections

- Desktop user → Desktop app: opens (evidence: `README.md`)
- Desktop app → File transcription: offers file workflow (evidence: `app.py`)
- Desktop app → Live recording: offers recording (evidence: `app.py`)
- File transcription → ASR engine: invokes (evidence: `tab_file.py`)
- File transcription → Audio decoding: uses (evidence: `tab_file.py`)
- Live recording → Audio quality: analyzes audio (evidence: `tab_live.py`)
- ASR engine → Audio decoding: decodes through (evidence: `core/asr_engine.py`)
- ASR engine → Voice activity detection: uses (evidence: `core/asr_engine.py`)
- ASR engine → Punctuation restoration: uses (evidence: `core/asr_engine.py`)
- ASR engine → Speaker diarization: uses (evidence: `core/asr_engine.py`)
- ASR engine → CAM++ diarization: uses (evidence: `core/asr_engine.py`)
- ASR engine → Overlap separation: uses (evidence: `core/asr_engine.py`)
- Desktop user → File transcription: submits audio (evidence: `README.md`)
- Web user → Web API: uploads audio (evidence: `README.md`)
- Web API → Authentication: checks access (evidence: `web_service/server.py`)
- Web API → Session lifecycle: tracks sessions (evidence: `web_service/server.py`)
- Web API → Job queue: enqueues jobs (evidence: `web_service/server.py`)
- Job queue → Service database: updates jobs (evidence: `web_service/queue_manager.py`)
- Job queue → ASR engine: runs transcription (evidence: `web_service/queue_manager.py`)
- Job queue → Meeting summarizer: dispatches summaries (evidence: `web_service/queue_manager.py`)
- Web API → Service database: reads and writes (evidence: `web_service/server.py`)
- Session lifecycle → Service database: stores session state (evidence: `web_service/session_manager.py`)
- Web API → GPU calibration: requests calibration (evidence: `web_service/server.py`)
- GPU calibration → Hardware providers: detects providers (evidence: `core/calibration.py`)
- GPU calibration → ASR engine: benchmarks stages (evidence: `core/calibration.py`)
- Desktop app → Model and app config: loads settings (evidence: `app.py`)
- ASR engine → Model and app config: reads model settings (evidence: `core/asr_engine.py`)
- Web API → Service config: uses settings (evidence: `web_service/server.py`)
- Service config → Model and app config: shares model config (evidence: `web_service/config.py`)
- Web user → PWA file server: opens offline app (evidence: `README.md`)
- PWA file server → Browser pipeline scaffold: serves browser shell
- Browser pipeline scaffold → ASR engine: inference not implemented
- ASR engine → Audio quality: evaluates quality (evidence: `README.md`)
- ASR engine → Punctuation restoration: restores punctuation (evidence: `README.md`)
- ASR engine → Speaker diarization: assigns speakers (evidence: `README.md`)
- ASR engine → Overlap separation: separates overlap (evidence: `README.md`)
