# sabtain-dev/stt-whisper-pashto architecture

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

- Interactive diagram: https://gitdiagram.com/sabtain-dev/stt-whisper-pashto
- Repository: https://github.com/sabtain-dev/stt-whisper-pashto

## Overview

This repository delivers Pakistani Pashto speech recognition through a Streamlit dashboard and a versioned FastAPI transcription service. The documented API path is upload, validation, temporary staging, Whisper inference and a structured response; inference preprocesses audio and loads the fine-tuned model. The README also describes dashboard editing, translation, WER evaluation and authentication, but app internals were not excerpted, so those capabilities are shown without guessed call links. Edges reflect excerpts or README statements; unsampled internals are not inferred.

Main entry points: [`app/app.py`](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py) (Streamlit dashboard), [`api/routes/transcription.py`](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/routes/transcription.py) (Transcription endpoints), [`api/main.py`](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/main.py) (FastAPI application), [`api/services/transcription_service.py`](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/services/transcription_service.py) (Transcription service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User dashboard"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
  node_editing["Text editing<br/>[app.py]"]
  node_translation["Translation<br/>[app.py]"]
  node_wer_eval["WER evaluation<br/>[app.py]"]
  node_auth["User authentication<br/>[app.py]"]
  node_api_client["API client<br/>[app.py]"]
end

subgraph group_api["REST service"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_errors["Exception handling<br/>[exceptions.py]"]
  node_transcription_route["Transcription endpoints<br/>[transcription.py]"]
  node_validation["Upload validation<br/>[validation.py]"]
  node_responses["Response schemas<br/>[response.py]"]
  node_service["Transcription service"]
  node_engine_cache["Shared engine cache<br/>[dependencies.py]"]
  node_temp_audio[("Temporary audio files")]
end

subgraph group_ml["Speech inference"]
  node_transcriber["Pashto transcriber<br/>[inference.py]"]
  node_audio_prep["Audio preprocessing<br/>[audio_utils.py]"]
  node_model_loader["Whisper model loading<br/>[model_utils.py]"]
end

node_user(("End user"))
node_model_hub[("Hugging Face model")]
node_audio_upload(("Audio upload"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"supports editing"| node_editing
node_dashboard -->|"supports translation"| node_translation
node_dashboard -->|"supports evaluation"| node_wer_eval
node_dashboard -->|"supports authentication"| node_auth
node_dashboard -->|"sends requests"| node_api_client
node_api_client -->|"HTTP requests"| node_api_entry
node_api_entry -->|"registers router"| node_transcription_route
node_api_entry -->|"configures routes"| node_settings
node_api_entry -->|"registers handlers"| node_errors
node_audio_upload -->|"posts audio"| node_transcription_route
node_transcription_route -->|"validates upload"| node_validation
node_transcription_route -->|"gets engine"| node_engine_cache
node_transcription_route -->|"calls service"| node_service
node_transcription_route -->|"returns schema"| node_responses
node_service -->|"checks formats"| node_settings
node_service -->|"stages and removes"| node_temp_audio
node_service -.->|"calls engine"| node_engine_cache
node_engine_cache -->|"constructs engine"| node_transcriber
node_transcriber -->|"preprocesses audio"| node_audio_prep
node_transcriber -->|"loads components"| node_model_loader
node_model_loader -->|"loads checkpoint"| node_model_hub
node_transcriber -->|"uses model and processor"| node_model_loader

click node_dashboard "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py"
click node_editing "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py"
click node_translation "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py"
click node_wer_eval "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py"
click node_auth "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py"
click node_api_client "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py"
click node_api_entry "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/main.py"
click node_settings "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/config.py"
click node_errors "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/exceptions.py"
click node_transcription_route "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/routes/transcription.py"
click node_validation "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/utils/validation.py"
click node_responses "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/schemas/response.py"
click node_service "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/services/transcription_service.py"
click node_engine_cache "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/dependencies.py"
click node_temp_audio "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/services/transcription_service.py"
click node_transcriber "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/utils/inference.py"
click node_audio_prep "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/utils/audio_utils.py"
click node_model_loader "https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/utils/model_utils.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_editing,node_translation,node_wer_eval,node_auth,node_api_client,node_user toneBlue
class node_api_entry,node_settings,node_errors,node_transcription_route,node_validation,node_responses,node_service,node_engine_cache,node_temp_audio,node_model_hub toneAmber
class node_transcriber,node_audio_prep,node_model_loader toneMint
class node_audio_upload toneIndigo
```

## Components

### User dashboard

- [Streamlit dashboard](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py): `app/app.py`
- [Text editing](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py): `app/app.py`
- [Translation](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py): `app/app.py`
- [WER evaluation](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py): `app/app.py`
- [User authentication](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py): `app/app.py`
- [API client](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/app/app.py): `app/app.py`

### REST service

- [FastAPI application](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/main.py): `api/main.py`
- [Runtime settings](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/config.py): `api/config.py`
- [Exception handling](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/exceptions.py): `api/exceptions.py`
- [Transcription endpoints](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/routes/transcription.py): `api/routes/transcription.py`
- [Upload validation](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/utils/validation.py): `api/utils/validation.py`
- [Response schemas](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/schemas/response.py): `api/schemas/response.py`
- [Transcription service](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/services/transcription_service.py): `api/services/transcription_service.py`
- [Shared engine cache](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/dependencies.py): `api/dependencies.py`
- [Temporary audio files](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/api/services/transcription_service.py): `api/services/transcription_service.py`

### Speech inference

- [Pashto transcriber](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/utils/inference.py): `utils/inference.py`
- [Audio preprocessing](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/utils/audio_utils.py): `utils/audio_utils.py`
- [Whisper model loading](https://github.com/sabtain-dev/stt-whisper-pashto/blob/main/utils/model_utils.py): `utils/model_utils.py`

### Other components

- **End user**
- **Hugging Face model**
- **Audio upload**

## Connections

- End user → Streamlit dashboard: uses (evidence: `README.md`)
- Streamlit dashboard → Text editing: supports editing (evidence: `README.md`)
- Streamlit dashboard → Translation: supports translation (evidence: `README.md`)
- Streamlit dashboard → WER evaluation: supports evaluation (evidence: `README.md`)
- Streamlit dashboard → User authentication: supports authentication (evidence: `README.md`)
- Streamlit dashboard → API client: sends requests (evidence: `README.md`)
- API client → FastAPI application: HTTP requests (evidence: `README.md`)
- FastAPI application → Transcription endpoints: registers router (evidence: `api/main.py`)
- FastAPI application → Runtime settings: configures routes (evidence: `api/main.py`)
- FastAPI application → Exception handling: registers handlers (evidence: `api/main.py`)
- Audio upload → Transcription endpoints: posts audio (evidence: `api/routes/transcription.py`)
- Transcription endpoints → Upload validation: validates upload (evidence: `api/routes/transcription.py`)
- Transcription endpoints → Shared engine cache: gets engine (evidence: `api/routes/transcription.py`)
- Transcription endpoints → Transcription service: calls service (evidence: `api/routes/transcription.py`)
- Transcription endpoints → Response schemas: returns schema (evidence: `api/routes/transcription.py`)
- Transcription service → Runtime settings: checks formats (evidence: `api/services/transcription_service.py`)
- Transcription service → Temporary audio files: stages and removes (evidence: `api/services/transcription_service.py`)
- Transcription service → Shared engine cache: calls engine
- Shared engine cache → Pashto transcriber: constructs engine (evidence: `api/dependencies.py`)
- Pashto transcriber → Audio preprocessing: preprocesses audio (evidence: `utils/inference.py`)
- Pashto transcriber → Whisper model loading: loads components (evidence: `utils/inference.py`)
- Whisper model loading → Hugging Face model: loads checkpoint (evidence: `utils/model_utils.py`)
- Pashto transcriber → Whisper model loading: uses model and processor (evidence: `utils/inference.py`)
