# naveedqadir/tajweeh architecture

> Architecture diagram of the GitHub repository naveedqadir/tajweeh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naveedqadir/tajweeh
- Repository: https://github.com/naveedqadir/tajweeh

## Overview

##### Project Type and Purpose
- This is a full-stack, ML-enabled Flask web application with a companion REST API for mobile clients.
- Purpose: analyze Qur’an recitations, perform Arabic speech recognition, verse detection, text alignment, acoustic tajwīd analysis, and present detailed feedback via a web UI or mobile apps.

##### Main Components
- User Interfaces
- Web UI (Flask + Jinja2 templates under templates/)
- Mobile App (Flutter example connecting to the REST API)
- Backend Services
- Flask Application (app.py) hosting both Web and API blueprints (api/auth.py, api/mobile.py)
- Authentication Service (JWT-based, under api/auth.py, models.py)
- ML Processing Engine (utils/asr.py, alignment.py, tajweed_checker.py, phonetic_analysis.py, feedback_system.py)
- Data Stores
- SQLite Database (instance/tajweed.db via SQLAlchemy models.py)
- Qur’an Data JSON files (data/quran_text.json, data/tajweed.json)
- Temporary file storage (uploads/)
- External Dependencies
- Hugging Face Models (wav2vec2 ASR)
- FFmpeg/Pydub for audio conversion
- Utility Scripts
- Data refresh (scripts/refresh_data.py)
- ASR fine-tuning (scripts/fine_tune_asr.py)

##### Component Relationships and Data Flow
- User → (HTTPS) → Web UI / REST API endpoints
- Web UI ↔ Authentication Service → Database (user/session management)
- REST API ↔ Authentication Service → Database
- File upload request → Audio Processing (format validation, conversion) → ML Pipeline
- ML Pipeline
- ASR Model → Transcript + word timestamps
- Verse Detection & Text Alignment → verse identification
- Tajwīd Analysis → mistake detection + feedback
- ML Pipeline → Store results in Database → Web UI / Mobile App fetch and display

##### Architectural Patterns and Design Principles
- Layered architecture:
- Presentation layer (templates + API responses)
- Business layer (Flask controllers + ML utilities)
- Data layer (SQLAlchemy models + JSON data)
- Modular structure: clear separation of web, API, utilities, models, scripts
- MVC-style pattern: models.py for data, app.py/controllers for routes, templates for views
- C4-style containerization: group services into “Frontend”, “Backend Services”, “ML Engine”, “Databases”, “External Systems”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        WebUI["Web UI (Flask + Jinja2)"]:::frontend
        MobileApp["Mobile App (Flutter)"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        WebApp["Web Application (Flask Templates)"]:::backend
        subgraph "API Server"
            AuthEP["Auth Endpoints (JWT)"]:::backend
            MobileEP["Mobile Endpoints"]:::backend
        end
    end

    %% ML Processing Engine
    subgraph "ML Engine"
        Audio["Audio Handler (FFmpeg/Pydub)"]:::ml
        ASR["ASR Module (wav2vec2)"]:::ml
        Align["Alignment Module"]:::ml
        Tajweed["Tajwīd Analysis"]:::ml
        Phonetic["Phonetic Analysis"]:::ml
        Feedback["Feedback Generation"]:::ml
        QuranData["Qur'an Data Loader"]:::ml
    end

    %% Data Layer
    subgraph "Data Layer"
        SQLiteDB["SQLite Database"]:::db
        QuranJSON["Qur'an JSON Store"]:::db
        Uploads["Temp File Storage"]:::db
    end

    %% External Systems
    subgraph "External Systems"
        HF["Hugging Face ASR Model"]:::external
        FFmpeg["FFmpeg / Pydub"]:::external
    end

    %% Utility Scripts
    subgraph "Utility Scripts"
        Refresh["Data Refresh Script"]:::script
        FineTune["ASR Fine-tuning Script"]:::script
    end

    %% Repository Files
    subgraph "Repository Files"
        Requirements["requirements.txt"]
        APIDoc["API_DOCUMENTATION.md"]
        APISummary["API_IMPLEMENTATION_SUMMARY.md"]
        EnvExample[".env.example"]
        Templates["templates/"]
    end

    %% Connections - User interactions
    User["User"]:::user -->|HTTPS/JSON| WebUI
    User -->|HTTPS/JSON| MobileApp

    %% Frontend to Backend
    WebUI -->|renders| WebApp
    WebApp -->|HTTPS/JSON| AuthEP
    MobileApp -->|HTTPS/JSON| MobileEP
    MobileEP -->|validates| AuthEP

    %% Authentication and Data
    AuthEP -->|SQL queries| SQLiteDB

    %% File upload and ML pipeline
    WebUI -->|file upload| Audio
    Audio -->|convert| FFmpeg
    Audio --> ASR
    ASR -->|transcript| Align
    Align -->|aligned verses| QuranData
    Align --> Tajweed
    Tajweed --> Phonetic
    Phonetic --> Feedback
    Feedback -->|store results| SQLiteDB

    %% Data layer interactions
    QuranData -->|load JSON| QuranJSON
    WebApp -->|read/write| Uploads
    WebApp -->|read| QuranJSON

    %% External model
    ASR -->|load model| HF

    %% Utility scripts to data
    Refresh -->|rebuild| QuranJSON
    Refresh -->|update| SQLiteDB
    FineTune -->|train| ASR

    %% Repository files references
    WebUI --- Templates
    WebApp --- Requirements
    AuthEP --- APIDoc
    AuthEP --- APISummary
    AuthEP --- EnvExample

    %% Click Events
    click WebUI "https://github.com/naveedqadir/tajweeh/tree/master/qurantajweeh_arabic/templates/"
    click MobileApp "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/flutter_example.dart"
    click WebApp "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/app.py"
    click AuthEP "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/api/auth.py"
    click MobileEP "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/api/mobile.py"
    click SQLiteDB "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/models.py"
    click ASR "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/utils/asr.py"
    click Audio "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/utils/audio.py"
    click Align "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/utils/alignment.py"
    click Tajweed "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/utils/tajweed_checker.py"
    click Phonetic "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/utils/phonetic_analysis.py"
    click Feedback "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/utils/feedback_system.py"
    click QuranData "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/utils/quran_data.py"
    click Refresh "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/scripts/refresh_data.py"
    click FineTune "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/scripts/fine_tune_asr.py"
    click Requirements "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/requirements.txt"
    click APIDoc "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/API_DOCUMENTATION.md"
    click APISummary "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/API_IMPLEMENTATION_SUMMARY.md"
    click EnvExample "https://github.com/naveedqadir/tajweeh/blob/master/qurantajweeh_arabic/.env.example"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef backend fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef ml fill:#FFCC99,stroke:#333,stroke-width:1px
    classDef db fill:#C2FABC,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef script fill:#F2F2F2,stroke:#333,stroke-width:1px
    classDef user fill:#B3D9FF,stroke:#333,stroke-width:1px
```
