# krishnag180805-star/vocaliq---ai-english-evaluator architecture

> Architecture diagram of the GitHub repository krishnag180805-star/vocaliq---ai-english-evaluator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krishnag180805-star/vocaliq---ai-english-evaluator
- Repository: https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator

## Overview

VocalIQ is a Streamlit speaking-practice evaluator. Learners choose a structured or custom prompt, speak to a timer, record or upload audio, and receive a transcript plus diagnostic scores and feedback. The main runtime path runs through the app’s audio validation/conversion, speech recognition, and linguistic evaluation before rendering results. The README documents optional cloud recognition and AI feedback alongside offline evaluation. Source excerpts support the core orchestration and evaluation steps; some UI and integration links rely on README documentation because the relevant app and evaluator sections are incomplete.

Main entry points: [`app.py`](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/app.py) (Streamlit app), [`src/evaluator.py`](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py) (Evaluation engine), [`src/stt_engine.py`](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/stt_engine.py) (Speech recognition), [`src/audio_processor.py`](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/audio_processor.py) (Audio validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_practice["Practice setup"]
  node_app["Streamlit app<br/>[app.py]"]
  node_topics["Topic library<br/>[topics.py]"]
  node_timer["Speaking timer<br/>[ui_components.py]"]
  node_config["Evaluation settings<br/>[config.py]"]
end

subgraph group_audio["Audio and recognition"]
  node_audio_input["Mic or upload<br/>[app.py]"]
  node_audio_processor["Audio validation<br/>[audio_processor.py]"]
  node_stt["Speech recognition<br/>[stt_engine.py]"]
  node_whisper["Local Whisper"]
  node_google_stt["Google speech API"]
  node_groq_stt["Groq Whisper"]
  node_error_handler["Audio recovery<br/>[error_handler.py]"]
end

subgraph group_assessment["Assessment"]
  node_evaluator["Evaluation engine<br/>[evaluator.py]"]
  node_grammar["Grammar analysis<br/>[evaluator.py]"]
  node_vocabulary["Vocabulary analysis<br/>[evaluator.py]"]
  node_fluency["Fluency analysis<br/>[evaluator.py]"]
  node_pronunciation["Pronunciation analysis<br/>[evaluator.py]"]
  node_gemini["Gemini AI"]
end

subgraph group_feedback["Results and guidance"]
  node_results["Evaluation report<br/>[evaluator.py]"]
  node_ui["Result components<br/>[ui_components.py]"]
  node_troubleshooting["Mic guidance<br/>[error_handler.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"selects prompts"| node_topics
node_app -->|"shows timer"| node_timer
node_app -->|"captures audio"| node_audio_input
node_audio_input -->|"validates audio"| node_audio_processor
node_audio_processor -->|"reads limits"| node_config
node_app -->|"requests transcript"| node_stt
node_stt -->|"transcribes locally"| node_whisper
node_stt -->|"falls back"| node_google_stt
node_stt -.->|"optionally calls"| node_groq_stt
node_app -->|"evaluates transcript"| node_evaluator
node_evaluator -->|"uses criteria"| node_config
node_evaluator -->|"analyzes grammar"| node_grammar
node_evaluator -->|"analyzes vocabulary"| node_vocabulary
node_evaluator -->|"analyzes fluency"| node_fluency
node_evaluator -->|"analyzes clarity"| node_pronunciation
node_evaluator -.->|"optionally enhances"| node_gemini
node_evaluator -->|"builds report"| node_results
node_app -->|"renders feedback"| node_ui
node_results -->|"displays scores"| node_ui
node_app -->|"handles audio errors"| node_error_handler
node_error_handler -->|"shows guidance"| node_troubleshooting

click node_app "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/app.py"
click node_topics "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/topics.py"
click node_timer "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/ui_components.py"
click node_config "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/config.py"
click node_audio_input "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/app.py"
click node_audio_processor "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/audio_processor.py"
click node_stt "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/stt_engine.py"
click node_error_handler "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/error_handler.py"
click node_evaluator "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py"
click node_grammar "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py"
click node_vocabulary "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py"
click node_fluency "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py"
click node_pronunciation "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py"
click node_results "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py"
click node_ui "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/ui_components.py"
click node_troubleshooting "https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/error_handler.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_app,node_topics,node_timer,node_config toneBlue
class node_audio_input,node_audio_processor,node_stt,node_whisper,node_google_stt,node_groq_stt,node_error_handler toneAmber
class node_evaluator,node_grammar,node_vocabulary,node_fluency,node_pronunciation,node_gemini toneMint
class node_results,node_ui,node_troubleshooting toneRose
class node_learner toneIndigo
```

## Components

### Practice setup

- [Streamlit app](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/app.py): `app.py`
- [Topic library](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/topics.py): `src/topics.py`
- [Speaking timer](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/ui_components.py): `src/ui_components.py`
- [Evaluation settings](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/config.py): `src/config.py`

### Audio and recognition

- [Mic or upload](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/app.py): `app.py`
- [Audio validation](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/audio_processor.py): `src/audio_processor.py`
- [Speech recognition](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/stt_engine.py): `src/stt_engine.py`
- **Local Whisper**
- **Google speech API**
- **Groq Whisper**
- [Audio recovery](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/error_handler.py): `src/error_handler.py`

### Assessment

- [Evaluation engine](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Grammar analysis](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Vocabulary analysis](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Fluency analysis](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Pronunciation analysis](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- **Gemini AI**

### Results and guidance

- [Evaluation report](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/evaluator.py): `src/evaluator.py`
- [Result components](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/ui_components.py): `src/ui_components.py`
- [Mic guidance](https://github.com/krishnag180805-star/vocaliq---ai-english-evaluator/blob/main/src/error_handler.py): `src/error_handler.py`

### Other components

- **Learner**

## Connections

- Learner → Streamlit app: uses (evidence: `README.md`)
- Streamlit app → Topic library: selects prompts (evidence: `README.md`)
- Streamlit app → Speaking timer: shows timer (evidence: `README.md`)
- Streamlit app → Mic or upload: captures audio (evidence: `README.md`)
- Mic or upload → Audio validation: validates audio (evidence: `README.md`)
- Audio validation → Evaluation settings: reads limits (evidence: `src/audio_processor.py`)
- Streamlit app → Speech recognition: requests transcript (evidence: `app.py`)
- Speech recognition → Local Whisper: transcribes locally (evidence: `src/stt_engine.py`)
- Speech recognition → Google speech API: falls back (evidence: `src/stt_engine.py`)
- Speech recognition → Groq Whisper: optionally calls (evidence: `src/stt_engine.py`)
- Streamlit app → Evaluation engine: evaluates transcript (evidence: `app.py`)
- Evaluation engine → Evaluation settings: uses criteria (evidence: `src/evaluator.py`)
- Evaluation engine → Grammar analysis: analyzes grammar (evidence: `README.md`)
- Evaluation engine → Vocabulary analysis: analyzes vocabulary (evidence: `README.md`)
- Evaluation engine → Fluency analysis: analyzes fluency (evidence: `README.md`)
- Evaluation engine → Pronunciation analysis: analyzes clarity (evidence: `README.md`)
- Evaluation engine → Gemini AI: optionally enhances (evidence: `README.md`)
- Evaluation engine → Evaluation report: builds report (evidence: `src/evaluator.py`)
- Streamlit app → Result components: renders feedback (evidence: `README.md`)
- Evaluation report → Result components: displays scores (evidence: `README.md`)
- Streamlit app → Audio recovery: handles audio errors (evidence: `app.py`)
- Audio recovery → Mic guidance: shows guidance (evidence: `src/error_handler.py`)
