# thiagohgl/ai-pronunciation-trainer architecture

> Architecture diagram of the GitHub repository thiagohgl/ai-pronunciation-trainer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thiagohgl/ai-pronunciation-trainer
- Repository: https://github.com/thiagohgl/ai-pronunciation-trainer

## Overview

Main Components to Include:

##### Frontend Layer
- Static assets (CSS/JavaScript) components

##### Backend Web Server
- WebApp.py as the main server component
- Use green for server components

##### Core Processing Components
- Speech Processing Module (whisper_wrapper.py)
- AI Models Module (AIModels.py)
- Rule-Based Models Module (RuleBasedModels.py)
- Word Processing Modules (WordMatching.py, WordMetrics.py)
- Use orange for processing components

##### Lambda Functions Layer
- Sample Generation (lambdaGetSample.py)
- Speech Scoring (lambdaSpeechToScore.py)
- Text-to-Speech (lambdaTTS.py)
- Use purple for lambda components

##### Data Storage
- Databases component (databases folder with CSV files)
- Pickle file storage (data_de_en_2.pickle)
- Use yellow for data storage components

Connection Flows:

##### User Interaction Flow
→ Frontend to web server
→ Web server to processing components

##### Processing Flow
→ Connect lambda functions to their respective processing components
→ Show data flow between storage and processing components

Specific Implementation Guidelines:

**[User Browser] → [Frontend (HTML/JS/CSS)] → [Web Server (Flask)]**
- ↑                                           ↓
- [Processing Pipeline]
- ↓
- [Data Storage]

**[Speech Input] → [Whisper ASR] → [AI Models]**
- ↓
**[Database] ←→ [Word Matching] ← [Rule-Based Models]**
- ↓
- [Score Output]

Key Architectural Patterns to Highlight:

##### Model-View-Controller (MVC) pattern
- View: templates/static files
- Controller: webApp.py
- Model: AIModels.py, RuleBasedModels.py

##### Interface-based design
- ModelInterfaces.py as a connection point
- Extensibility for new languages

##### Service-oriented architecture
- Lambda functions as independent services
- Clear separation of concerns

- Use rectangles for standard components
- Use hexagons for server components
- Use clouds for external services (like ffmpeg)

- Notes about language extension points
- Document external dependencies

Level of Detail:

- Clear separation between web interface, processing logic, and data storage
- Extension points for new languages as mentioned in the README
- ASR model integration points

Remember to add notes about:
- FFmpeg dependency
- Browser compatibility (Chrome-focused)
- Language extension points
- Model interfaces for new ASR implementations

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        UI["Web Interface"]:::frontend
        CSS["Styling"]:::frontend
        JS["Client Logic"]:::frontend
        UI --> CSS
        UI --> JS
    end

    subgraph Server
        WS["Web Server"]:::server
    end

    subgraph Processing
        SP["Speech Processing"]:::processing
        AIM["AI Models"]:::processing
        RBM["Rule-Based Models"]:::processing
        WM["Word Matching"]:::processing
        WME["Word Metrics"]:::processing
        MI["Model Interfaces"]:::processing
        
        SP --> AIM
        AIM --> RBM
        RBM --> WM
        WM --> WME
        MI --> AIM
        MI --> RBM
    end

    subgraph Lambda
        LGS["Sample Generation"]:::lambda
        LSS["Speech Scoring"]:::lambda
        LTTS["Text-to-Speech"]:::lambda
    end

    subgraph Storage
        EDB["English Database"]:::storage
        GDB["German Database"]:::storage
        PKL["Pickle Storage"]:::storage
    end

    subgraph Utilities
        FIO["File I/O"]:::utility
        PT["Pronunciation Trainer"]:::utility
    end

    UI --> WS
    WS --> SP
    WS --> LGS
    WS --> LSS
    WS --> LTTS
    
    WM --> EDB
    WM --> GDB
    WM --> PKL
    
    FIO --> Storage
    PT --> Processing

    %% Click Events
    click UI "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/templates/main.html"
    click CSS "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/static/css/style-new.css"
    click JS "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/static/javascript/callbacks.js"
    click WS "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/webApp.py"
    click SP "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/whisper_wrapper.py"
    click AIM "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/AIModels.py"
    click RBM "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/RuleBasedModels.py"
    click WM "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/WordMatching.py"
    click WME "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/WordMetrics.py"
    click MI "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/ModelInterfaces.py"
    click LGS "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/lambdaGetSample.py"
    click LSS "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/lambdaSpeechToScore.py"
    click LTTS "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/lambdaTTS.py"
    click EDB "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/databases/data_en.csv"
    click GDB "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/databases/data_de.csv"
    click PKL "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/data_de_en_2.pickle"
    click FIO "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/utilsFileIO.py"
    click PT "https://github.com/Thiagohgl/ai-pronunciation-trainer/blob/main/pronunciationTrainer.py"

    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef server fill:#2ecc71,stroke:#27ae60,color:white
    classDef processing fill:#e67e22,stroke:#d35400,color:white
    classDef lambda fill:#9b59b6,stroke:#8e44ad,color:white
    classDef storage fill:#f1c40f,stroke:#f39c12,color:black
    classDef utility fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Legend
    subgraph Legend
        F[Frontend]:::frontend
        S[Server]:::server
        P[Processing]:::processing
        L[Lambda]:::lambda
        ST[Storage]:::storage
        U[Utility]:::utility
    end
```
