How naveedqadir/tajweeh works
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”